Sold Market Statistics

GET /v4/market-statistics

Get market statistics based on search criteria. This endpoint returns aggregated statistics for any listings that have sold within a specified timeframe.

Required: Filters must include either a boundary-id or an MLS plus one additional area filter. Area filters include city, area-level-1, area-level-2, and postal-code.

Request

Query Parameters

time-interval stringrequired

This is the interval of time you want aggregated market statistics for. This is an ISO 8601 time Interval with either

a start and end time
a start time and duration
or a duration and end time

Specifying a begin date retrieves all data for that day. Specifying an end date retrieves all data before that day. To get an entire month's worth of data, specify the first day of the month in question and the first day of the following month. Time values in the range are discarded.

For example, passing a time interval of 2024-04-01/2024-05-01 or 2024-04-01/P1M will return all data for April 2024. If you pass 2024-04-01/2024-04-30 or 2024-04-01T00:00:00/2024-04-3T23:59:59 you might be expecting all of April, but you'd end up missing data from April 30 in both cases.

More information on ISO 8601 durations can be found here.

Example: &time-interval=P1Y/2008-05-11T15:30:00Z

mls string[]

The MLS code you want associated boundary IDs from.

Example: &mls=recolorado&mls=pikespeak

boundary-id string[]

The boundary id or ids you want aggregated market statistics for. Boundary ids are the only way to get data by legally defined geometry. All other parameters like city, search on the postal address. See Cities vs Postal Cities. By default, all boundary IDs will be grouped together. If you want to group by individual boundary IDs, you can use the

group-by

query parameter. Note: at least one boundary-id, city, local-area-1, local-area-2, or postal-code is required.

Example: &boundary-id=593979d6da3374b282bb7bbb&boundary-id=593979d6da3374b282bb7bcb

property-type string[]

The property type or types you want aggregated market statistics for.

Possible values: [Residential, ResidentialLease, Commercial, CommercialLease, Land, Industrial, Other, Timeshare]

Default value: [Residential]

Example: &property-type=Residential&property-type=Commercial

property-sub-type string[]

The property sub type or sub types you want aggregated market statistics for. Sub Types are used to distinguish between the types of residential or commercial data available.

For instance, the most common suburban home would be a SingleFamilyResidence. A Condominium is usually defined as a subsection of a building made to be a place of dwelling. The place of dwelling is usually only 1 story tall. A Townhouse is usually a multilevel building attached to other multilevel buildings with no dwelling above or below it. See the RESO Standard Lookups for more information on property sub types.

Disclaimer: LiveBy ensures the availability of SingleFamilyResidence, Townhouse, and Condominium in each MLS. The availability of other PropertySubTypes may vary and is more limited by MLS.

Possible values: [SingleFamilyResidence, Agriculture, Apartment, BoatSlip, Business, Cabin, Condominium, DeededParking, Farm, Hotel, Industrial, ManufacturedHome, MixedUse, Mobile, MultiFamily, Office, OwnYourOwn, Ranch, Retail, StockCooperative, Timeshare, Townhouse, Land, Warehouse, Other]

Default value: [SingleFamilyResidence, Condominium, Townhouse]

Example: &property-sub-type=SingleFamilyResidence&property-sub-type=Condominium

city string[]

The postal city or cities you want aggregated market statistics for. You can use this instead of a boundary id. This uses the RESO Standard field “City”.

Example: &city=Lincoln&city=Omaha

area-level-1 string[]

The first political subdivision you want aggregated market statistics for. You can use this instead of a boundary id. This is often called “state”, “province” or “district” in various countries. This uses the RESO standard field “StateOrProvince”.

Example: &area-level-1=Nebraska&area-level-1=Iowa

area-level-2 string[]

The second political subdivision you want aggregated market statistics for. You can use this instead of a boundary id. This uses the RESO standard field “CountyOrParish”.

Example: &area-level-2=Lancaster&area-level-2=Seward

postal-code string[]

The postal code or codes you want aggregated market statistics for. You can use this instead of a boundary id. This uses the RESO standard field “PostalCode”.

Example: &postal-code=68521&postal-code=68502

mls-area-major string[]

The MLS Area Major for which you want market statistics.

Example: &mls-area-major=napa

outlier-original-list-price-low number

LiveBy by default cleans the data to remove outliers. LiveBy does not remove outlier data from the total counts, only the field’s counts, and statistics. You can use the count value of each field to determine if that field had outliers and was available from the MLS data sources.

Default value: 5000

Example: &outlier-original-list-price-low=5000

outlier-original-list-price-high number

Default value: 1000000000

Example: &outlier-original-list-price-high=1000000000

outlier-list-price-low number

Default value: 5000

Example: &outlier-list-price-low=5000

outlier-list-price-high number

Default value: 1000000000

Example: &outlier-list-price-high=1000000000

outlier-close-price-low number

Default value: 5000

Example: &outlier-close-price-low=5000

outlier-close-price-high number

Default value: 1000000000

Example: &outlier-close-price-high=1000000000

outlier-days-on-market-low number

Example: &outlier-days-on-market-low=0

outlier-days-on-market-high number

Default value: 1000

Example: &outlier-days-on-market-high=1000

outlier-living-area-low number

Example: &outlier-living-area-low=0

outlier-living-area-high number

Default value: 10000

Example: &outlier-living-area-high=10000

outlier-year-built-low number

Default value: 1700

Example: &outlier-year-built-low=1700

outlier-year-built-high number

Default value: 2025

Example: &outlier-year-built-high=2025

close-price-low number

This removes any listings that have a close price less than the value specified. Unlike the outlier filter, this will remove listings from all statistics, not just the price statistics.

Example: &close-price-low=100000

close-price-high number

This removes any listings that have a close price more than the value specified. Unlike the outlier filter, this will remove listings from all statistics, not just the price statistics.

Example: &close-price-high=10000000

group-by string[]

This lets you group data by date range using one of the options provided below.

If this is not specified you will get an aggregate of all data. This is useful for making rolling averages of data.

If you specify two years of data by using

&time-interval=2022-01-01T00:00:00Z/P2Y

and group by year, you will get an array of 3 results.

The first array will be for the first year, and the second array will be for the second year. You will also get an aggregate of all data combined.

If you specify quarter, you will get 11 results in the array, 8 quarters, (4 quarters * 2 years) + 2 years + 1 total.

If you specify month, you will get 27 results in the array, 24 months (12 months * 2 years) + 2 years + 1 total.

For information on grouping by price, see the price-segments parameter.

If you would like to get multiple boundaries, you can also specify

&group-by=boundary-id

If you would like to get data groupbed by PropertySubType, you can also specify

&group-by=property-sub-type

If you would like to get data groupbed by PropertyType, you can also specify

&group-by=property-type

If you specify multiple group-by parameters that are time ranges, only the first will be used.

Possible values: [year, quarter, month, week, boundary-id, property-sub-type, property-type]

Example: &group-by=month

price-segment string[]

If this parameter is provided, an aggregate is created for each price range defined by the price / segments provided. It is implied that the first price range starts at 0. Also, the low price is / inclusive (>=) and the high price is exclusive (<). See the example below.

You may specify many different ranges of prices.

This will always provide one more range than the number of price-segment parameters provided.

In this example, the price range aggregates will be:

0 - 499,999
500,000 - 999,999
1,000,000 - 1,499,999
1,500,000 +

Example: &price-segment=500000&price-segment=1000000&price-segment=1500000

Responses

application/json

Schema
Example (from schema)

Schema

success booleanrequired

data

object[]

Array [

period string

Time period these statistics are based on. In the format {full year} or {full year}-Q{quarter} or {full year}-M{month} or {full year}-W{week}

priceRange string[]

Price range of the properties

boundaryId string[]

If the query is grouping by boundary id, this is the id of the boundary.

PropertySubType string[]

If the query is grouping by property sub type, this is the property sub type.

PropertyType string[]

If the query is grouping by property type, this is the property type.

metadata objectrequired

The MLSes that provided data for these statistics

Example: {"attribution":[{"name":"North MLS"},{"name":"Northeast MLS"}]}

data

object

required

count numberrequired

Total count of listings within the period

ListPrice

object

required

Statistics about the price that the property was listed for when it sold

count numberrequired

Amount of non null and numeric values used to make statistics that is within the outlier range specified

Example: 10

median numberrequired

Median of the non null and numeric values that is within the outlier range specified

Example: 500000

average numberrequired

Mean average of the non null and numeric values that is within the outlier range specified

Example: 532561

minimum numberrequired

Smallest value of the non null and numeric values that is within the outlier range specified

Example: 100000

maximum numberrequired

Largest value of the non null and numeric values that is within the outlier range specified

Example: 20000000

sum numberrequired

Total sum of the non null and numeric values that is within the outlier range specified

Example: 256373500

OriginalListPrice

object

required

Statistics about the First List Price before price adjustments

count numberrequired

Amount of non null and numeric values used to make statistics that is within the outlier range specified

Example: 10

median numberrequired

Median of the non null and numeric values that is within the outlier range specified

Example: 500000

average numberrequired

Mean average of the non null and numeric values that is within the outlier range specified

Example: 532561

minimum numberrequired

Smallest value of the non null and numeric values that is within the outlier range specified

Example: 100000

maximum numberrequired

Largest value of the non null and numeric values that is within the outlier range specified

Example: 20000000

sum numberrequired

Total sum of the non null and numeric values that is within the outlier range specified

Example: 256373500

ClosePrice

object

required

Statistics about the price that the property was sold for

count numberrequired

Amount of non null and numeric values used to make statistics that is within the outlier range specified

Example: 10

median numberrequired

Median of the non null and numeric values that is within the outlier range specified

Example: 500000

average numberrequired

Mean average of the non null and numeric values that is within the outlier range specified

Example: 532561

minimum numberrequired

Smallest value of the non null and numeric values that is within the outlier range specified

Example: 100000

maximum numberrequired

Largest value of the non null and numeric values that is within the outlier range specified

Example: 20000000

sum numberrequired

Total sum of the non null and numeric values that is within the outlier range specified

Example: 256373500

YearBuilt

object

required

Statistics about the year the properties were built

count numberrequired

Amount of non null and numeric values used to make statistics that is within the outlier range specified

Example: 10

median numberrequired

Median of the non null and numeric values that is within the outlier range specified

Example: 500000

average numberrequired

Mean average of the non null and numeric values that is within the outlier range specified

Example: 532561

minimum numberrequired

Smallest value of the non null and numeric values that is within the outlier range specified

Example: 100000

maximum numberrequired

Largest value of the non null and numeric values that is within the outlier range specified

Example: 20000000

sum numberrequired

Total sum of the non null and numeric values that is within the outlier range specified

Example: 256373500

DaysOnMarket

object

required

Statistics about the number of days the property was on the market. This field is specified by an MLS, and can often be null. If Days On Market is missing from an MLS, either daysToClose or daysToContract should be used.

count numberrequired

Amount of non null and numeric values used to make statistics that is within the outlier range specified

Example: 10

median numberrequired

Median of the non null and numeric values that is within the outlier range specified

Example: 500000

average numberrequired

Mean average of the non null and numeric values that is within the outlier range specified

Example: 532561

minimum numberrequired

Smallest value of the non null and numeric values that is within the outlier range specified

Example: 100000

maximum numberrequired

Largest value of the non null and numeric values that is within the outlier range specified

Example: 20000000

sum numberrequired

Total sum of the non null and numeric values that is within the outlier range specified

Example: 256373500

CumulativeDaysOnMarket

object

required

Statistics about the total number of days the property was on the market. This differs from Days On Market because Days On Market is reset when the property is temporarily removed from market, while Cumulative Days On Market never resets. The outlier parameters for Days On Market also remove outliers from Cumulative Days On Market. This field is specified by an MLS, and can often be null.

count numberrequired

Amount of non null and numeric values used to make statistics that is within the outlier range specified

Example: 10

median numberrequired

Median of the non null and numeric values that is within the outlier range specified

Example: 500000

average numberrequired

Mean average of the non null and numeric values that is within the outlier range specified

Example: 532561

minimum numberrequired

Smallest value of the non null and numeric values that is within the outlier range specified

Example: 100000

maximum numberrequired

Largest value of the non null and numeric values that is within the outlier range specified

Example: 20000000

sum numberrequired

Total sum of the non null and numeric values that is within the outlier range specified

Example: 256373500

LivingArea

object

required

Statistics about the square footage of the properties

count numberrequired

Amount of non null and numeric values used to make statistics that is within the outlier range specified

Example: 10

median numberrequired

Median of the non null and numeric values that is within the outlier range specified

Example: 500000

average numberrequired

Mean average of the non null and numeric values that is within the outlier range specified

Example: 532561

minimum numberrequired

Smallest value of the non null and numeric values that is within the outlier range specified

Example: 100000

maximum numberrequired

Largest value of the non null and numeric values that is within the outlier range specified

Example: 20000000

sum numberrequired

Total sum of the non null and numeric values that is within the outlier range specified

Example: 256373500

pricePerSquareFoot

object

required

Statistics about the price per square foot of the properties

count numberrequired

Amount of non null and numeric values used to make statistics that is within the outlier range specified

Example: 10

median numberrequired

Median of the non null and numeric values that is within the outlier range specified

Example: 500000

average numberrequired

Mean average of the non null and numeric values that is within the outlier range specified

Example: 532561

minimum numberrequired

Smallest value of the non null and numeric values that is within the outlier range specified

Example: 100000

maximum numberrequired

Largest value of the non null and numeric values that is within the outlier range specified

Example: 20000000

sum numberrequired

Total sum of the non null and numeric values that is within the outlier range specified

Example: 256373500

daysToClose

object

required

Statistics about the number of days until the property was sold. This is calculated from the List Date to the Close Date, which is most often the date the title was changed, not the date the property was received an offer.

count numberrequired

Amount of non null and numeric values used to make statistics that is within the outlier range specified

Example: 10

median numberrequired

Median of the non null and numeric values that is within the outlier range specified

Example: 500000

average numberrequired

Mean average of the non null and numeric values that is within the outlier range specified

Example: 532561

minimum numberrequired

Smallest value of the non null and numeric values that is within the outlier range specified

Example: 100000

maximum numberrequired

Largest value of the non null and numeric values that is within the outlier range specified

Example: 20000000

sum numberrequired

Total sum of the non null and numeric values that is within the outlier range specified

Example: 256373500

daysToContract

object

required

Statistics about the number of days until the property was sold. This is calculated from the List Date to the Contract Date, which is most often the date the property was received an offer, not the date the title was changed.

count numberrequired

Amount of non null and numeric values used to make statistics that is within the outlier range specified

Example: 10

median numberrequired

Median of the non null and numeric values that is within the outlier range specified

Example: 500000

average numberrequired

Mean average of the non null and numeric values that is within the outlier range specified

Example: 532561

minimum numberrequired

Smallest value of the non null and numeric values that is within the outlier range specified

Example: 100000

maximum numberrequired

Largest value of the non null and numeric values that is within the outlier range specified

Example: 20000000

sum numberrequired

Total sum of the non null and numeric values that is within the outlier range specified

Example: 256373500

soldOverAskingCount numberrequired

Count of listings that the Sold Price was greater than the final List Price

Example: 15

priceReductionCount numberrequired

Count of listings that the final List Price was less than the Original List Price

Example: 10

priceReductionPercentage numberrequired

Percentage of listings that the final List Price was less than the Original List Price

Example: 3.23

saleToListRatio numberrequired

Ratio of the final Sale Price divided by the List Price

Example: 1.05

]

{
  "success": true,
  "data": [
    {
      "period": "string",
      "priceRange": [
        "string"
      ],
      "boundaryId": [
        "string"
      ],
      "PropertySubType": [
        "string"
      ],
      "PropertyType": [
        "string"
      ],
      "metadata": {
        "attribution": [
          {
            "name": "North MLS"
          },
          {
            "name": "Northeast MLS"
          }
        ]
      },
      "data": {
        "count": 0,
        "ListPrice": {
          "count": 10,
          "median": 500000,
          "average": 532561,
          "minimum": 100000,
          "maximum": 20000000,
          "sum": 256373500
        },
        "OriginalListPrice": {
          "count": 10,
          "median": 500000,
          "average": 532561,
          "minimum": 100000,
          "maximum": 20000000,
          "sum": 256373500
        },
        "ClosePrice": {
          "count": 10,
          "median": 500000,
          "average": 532561,
          "minimum": 100000,
          "maximum": 20000000,
          "sum": 256373500
        },
        "YearBuilt": {
          "count": 10,
          "median": 500000,
          "average": 532561,
          "minimum": 100000,
          "maximum": 20000000,
          "sum": 256373500
        },
        "DaysOnMarket": {
          "count": 10,
          "median": 500000,
          "average": 532561,
          "minimum": 100000,
          "maximum": 20000000,
          "sum": 256373500
        },
        "CumulativeDaysOnMarket": {
          "count": 10,
          "median": 500000,
          "average": 532561,
          "minimum": 100000,
          "maximum": 20000000,
          "sum": 256373500
        },
        "LivingArea": {
          "count": 10,
          "median": 500000,
          "average": 532561,
          "minimum": 100000,
          "maximum": 20000000,
          "sum": 256373500
        },
        "pricePerSquareFoot": {
          "count": 10,
          "median": 500000,
          "average": 532561,
          "minimum": 100000,
          "maximum": 20000000,
          "sum": 256373500
        },
        "daysToClose": {
          "count": 10,
          "median": 500000,
          "average": 532561,
          "minimum": 100000,
          "maximum": 20000000,
          "sum": 256373500
        },
        "daysToContract": {
          "count": 10,
          "median": 500000,
          "average": 532561,
          "minimum": 100000,
          "maximum": 20000000,
          "sum": 256373500
        },
        "soldOverAskingCount": 15,
        "priceReductionCount": 10,
        "priceReductionPercentage": 3.23,
        "saleToListRatio": 1.05
      }
    }
  ]
}

Sold Market Statistics

/v4/market-statistics

Request​

Query Parameters

Responses​

Request

Responses