Skip to main content

Market Statistics

BetaUS 🇺🇸

Description​

Query to receive detailed market statistics within a neighborhood, city, zip code, or metro area, over time and divided by asset class. In the United States, the data returned covers a number of market statistics in the queried area based on homes listed for sale and sold homes which is updated every day:

  • Listing data metrics
    • Active listings count
    • Pending listings count
    • Listings under contract count
    • New listings count
    • Active listings' median age
    • Active listings' median property size in square feet
  • Home asking prices
    • Minimum asking price
    • Median asking price
    • Maximum asking price
    • Detailed percentile breakdowns on asking prices
    • Median asking price per square foot
  • Total count of homes sold
  • Home sales prices
    • Minimum sales price
    • Maximum sales price
    • Median sales price
    • Detailed percentile breakdowns on sales prices
    • Median sales price per square foot
    • Median dollar difference between asking and sales prices
    • Median percentage difference between asking and sales prices
    • Percent of homes sold above & below asking price
  • Median construction year of homes sold
  • Median property size in square feet of homes sold
  • Absorption rate (a measure of supply & demand calculated by homes sold divided by total listings)
  • Total sales volume in dollars
  • Market conditions assessment (buyer's/seller's/netural market) with numeric qualifier
  • Market speed
    • Median days on market
    • Median days to offer
    • Detailed percentile breakdowns of days to sell
Deprecated Endpoint: v3/marketstats

Local Logic updated our market statistics API in December 2024. This update expanded our in-depth analysis on market activity in neighborhoods and cities across the United States by incorporating listing data and moving from weekly to daily updates of our statistics. The previous version of the endpoint was v3/marketstats and its documentation can be found here.

Structure​

This endpoint returns data structured as a tree with muliple branches to allow consumers to view data at the appropriate level quickly. The data is organized first by asset class (e.g., condo/townhome, single-family residence, multi-family residences, etc), and then is provided at all requested intervals as outlined in the parameters below.

For each interval, the following is provided:

  • A description of the time period, with period start and end date and timestamps
  • A market activity dictionary containing the point-in-time statistics at the end of the interval (including active listing count, home asking prices breakdown, median days on the market for active listings)
  • A market activity dictionary containing the statistics computed over the entire interval (including total homes sold, new listing count, assessment of market conditions)
"Missing" Intervals

Any intervals where there are no listings were found at the end of the period, or where no homes were reported sold will not contain detailed statistics. These "missing intervals" are highlighted in the response of the API, as explained below in the Market Activity Intervals subsection.

GET v3/market-stats/{geog_id}​

Accepted values for geog_id are those matching g10_*, g20_*, g30_*, g32_*, g35_*, and g40_*. Other values will result with a 404 (not found) status code. A geog_id can be obtained for a desired neighborhood, city, zip code, or metro area using the Geographies endpoint.

GET v3/market-stats/{geog_id}

This API uses JWT token based authentication. This JWT Bearer token is what is used to populate the Authorization header below.

Instructions on how to retrieve this token can be found at Getting Started.

HeaderStatusDescription
AuthorizationrequiredYour bearer token retrieved from our authorization API, ex. Bearer eyJhbGci...
AcceptrequiredThe datatype to request, this API will return application/json.

QueryString​

ParameterStatusDescription
property_typesoptionalA comma-separated list of property types to include.
Accepted values are single_family, multi_family_under_5_units, condo_townhome, vacant_land, and multi_family_5_plus_units.
all_residential_properties can be used to combine the results for single_family, multi_family_under_5_units and condo_townhome property types.
Default: single_family, multi_family_under_5_units, condo_townhome, and all_residential_properties will be returned.
intervalsoptionalA comma-separated list of intervals to include, leveraging the interval codes explained below.
Default: The last 30 days and the latest 12 complete calendar months.
For example: 30d,2024-09,2024-08,2024-07,2024-06,2024-05,2024-04,2024-03,2024-02,2024-01,2023-12,2023-11,2023-10

Market Activity Intervals​

Because market activity statistics can be reviewed at many different type of intervals, this endpoint allows consumers to specify which intervals they would like to receive in their response. A combination of pre-set relative intervals are available in addition to allowing users to specific specific calendar months and years. If no interval is provided the endpoint will return the last 30 days and the 12 most recent "complete" calendar months available.

Interval codeDescription
30dThe previous 30 days from the current date.
31-60dThe past 31 to 60 days from the current date, helpful for comparing against the most recent 30 days.
12mThe previous 12 months from the current date.
13-24mThe past 13 to 24 months from the current date, helpful for comparing against the most recent 12 months.
[yyyy]-[mm]Any specific month in the past 5 years, formatted as a four digit year, hyphen, and two digit month. Ex: 2024-09, 2022-10, 2020-04

Any missing sections due to a lack of data (zero active listings at the end of the interval, or zero sales during the interval) will be highlighted in the meta section of response, with both a human-readable message and all of the combinations of property_type and interval which are missing some market stats. Here is an example of this section:

"meta": {
    "message": "The following intervals are missing some market activity data due to a low number of listings or sold homes: ['30d', '31-60d', '12m', '13-24m']",
    "missing_intervals": {
        "condo_townhome": [
            "30d",
            "31-60d"
        ],
        "multi_family_under_5_units": [
            "30d",
            "31-60d",
            "12m",
            "13-24m"
        ]
    }
}

Usage examples​

  require('node-fetch')('https://api.locallogic.co/v3/market-stats/g30_c28wnknk"?' + new URLSearchParams({
  }), {
    method: 'GET',
    headers: {
      Accept: 'application/json',
      Authorization: 'Bearer eyJhbGciOiJ...'
    }
  })
    .then(response => response.json())
    .then(body => {
      console.log(body)
    })
    .catch(error => {
      console.log(error)
    })

Response example​

Here is a link to a sample response for Boston, Massachusetts (g30_dp3t37v8) from Thursday, December 12, 2024.

Error codes​

When calling Local Logic’s API, you may receive an HTTP error code. These errors are explained below. In general, error codes starting with “4” are due to an invalid API call and can be fixed on your end, whereas error codes starting with “5” are due to server errors (that is, problems on our end). If you receive something not described here, please contact us at support@locallogic.co.

400 - BadRequest

This error code happens when the request inputs are incorrect. Use the detail field of the response for clarification. Example:

{
  "code": "LocalLogic.API.BadRequest",
  "detail": "ValidationErrors: AroundEndpoint is invalid:\n\tinclude is invalid: \"bad_input\" is not an acceptable value: \"groceries\", \"restaurants\", \"nightlife\", \"cafes\", \"shopping\", \"daycares\", \"primary_schools\", \"high_schools\""
}

401 - Unauthorized

This error code happens when your API key cannot access specific resources or locations. For example, some API keys can only access certain countries / states / provinces. Feel free to contact us for more information. Example:

{
  "code": "LocalLogic.API.Unauthorized",
  "detail": "Your API KEY doesn't support this region"
}

403 - Forbidden

This error code happens when you forgot to include security credentials with your request or you are requesting a parameter that you do not have access to. Example:

{
  "message": "Forbidden"
}

404 - NotFound

This error code happens when we don’t have data for the requested location. For example, if you send a lat/lng pair for a location in Antarctica, we will return this error as we don’t have data for Antarctica (yet!). Example:

{
  "code": "LocalLogic.API.NotFound",
  "detail": "No Location Scores found for this location."
}

422 - Unprocessable Entity

This error code is returned when the correct parameters have been sent however, the data they contain is not valid. For example, if you send a lat/lng pair and the latitude is invalid (ie. not in the range [-90, 90]) and/or the longitude is invalid (ie. not in the range [-180, 180]).

{
  "message": "Latitude must be within [-90, 90], Longitude must be within [-180, 180], Requires at least lat/lng pair, or geography_ids. None supplied.",
  "code": "LocalLogic.API.BadRequest",
  "statusCode": 422
}

500 - ServerError

This error code means that an error occurred on our end. Feel free to retry the same request to see if the problem persists. If you received a lot of these errors, please contact us at support@locallogic.co Example:

{
  "code": "LocalLogic.API.ServerError",
  "detail": "No Location Scores found for this location."
}

502 - BadGateway

This error code means that an error came from our cloud provider. Feel free to retry the same request to see if the problem persists. Example:

{
  "message": "Internal server error"
}