> ## Knowledge Base Index > Fetch the complete knowledge base index at: https://help.repliers.com/sitemap.xml > Use this file to discover available pages before exploring further. > Pure-Markdown content can be obtained by appending a '.md' suffix to the content URLs listed in the sitemap (without the trailing slash). # Real-Time Market Statistics Implementation Guide Our Real Estate API offers a powerful feature that allows you to request real-time market statistics. This capability is invaluable for creating data visualizations, providing users with deep market insights to make more informed decisions. The feature offers a high level of granularity, enabling you to request specific scopes of market data just as you would when filtering listings. # How to Request Statistics ### Step 1: Provide the Scope of Data Begin by defining the scope of the data you wish to analyze using the GET /listings endpoint. This scope is defined in the same way you would filter for listings. For example, if you want statistics for 4-bedroom homes in New York City that have sold in the past 2 years, your request URL will look like this: ``` https://api.repliers.io/listings?city=New York&minBeds=4&maxBeds=4&status=U&lastStatus=Sld&minSoldDate=2022-07-01 ``` ###### Important: Status Parameter for Statistics When using our API, the `status` parameter defaults to 'A' (Active) if not specified. However, many statistics require data from unavailable listings to be accurate. **Why this matters:** Statistics like average sold price can only be calculated using sold listings, which have a status of 'U' (Unavailable). Active listings don't contain sold price information since they haven't been sold yet. **What to do:** When requesting statistics that depend on sold or completed listings, always include `status=U` in your API request. Additionally, consider filtering by `lastStatus` since unavailable listings can have different outcomes: * **Sld** - Contains sold price data * **Ter** - Removed by owner * **Exp** - Listing period ended **Example:** * ❌ Without status (defaults to Active): Limited statistics available * ✅ With `status=U`: Access to all unavailable listings * ✅ With `status=U` + `lastStatus=Sld`: Most accurate for sold price statistics ###### Important: Date Filters Determine Which Date Field Statistics Use Repliers tracks two distinct dates for a completed transaction: * **`soldDate`** - The date the purchase contract was accepted (the offer acceptance date). Maps to the MLS `PurchaseContractDate` field. * **`closedDate`** - The date the transaction actually closed. Maps to the MLS `CloseDate` field. The date filter you use in your request determines which of these fields statistics are calculated against: | Filters used | Date field used for statistics | Underlying MLS field | | --- | --- | --- | | `minSoldDate` / `maxSoldDate` | `soldDate` | `PurchaseContractDate` | | `minClosedDate` / `maxClosedDate` | `closedDate` | `CloseDate` | This applies to all statistics, including counts such as `cnt-closed`, and to time-based groupings (`grp-mth`, `grp-yr`). For example, a request with `minSoldDate` groups and counts transactions by the month the contract was accepted, while the same request with `minClosedDate` groups and counts them by the month the transaction closed. **A note on terminology:** In many U.S. markets, the term "Sold Date" is commonly used to refer to the actual closing date (`CloseDate`). In Repliers, `soldDate` refers to the purchase contract (offer acceptance) date, not the closing date. If your use case depends on when transactions actually closed, use the `minClosedDate` / `maxClosedDate` filters. ### Step 2: Specify the Statistics To retrieve specific statistics, use the statistics parameter. For example, if you're interested in the average sold price, add &statistics=avg-soldPrice to your request. The full request URL would be: ``` https://api.repliers.io/listings?city=New York&minBeds=4&maxBeds=4&status=U&lastStatus=Sld&minSoldDate=2022-07-01&statistics=avg-soldPrice ``` This request will return all relevant listings along with a statistics object containing the average sold price: ```json { "statistics": { "soldPrice": { "avg": 823702 } } } ``` ###### Requesting Only Statistics If you do not need the listings and only require the statistics, add &listings=false to your request. This can significantly reduce response time. For instance: ``` https://api.repliers.io/listings?city=New York&minBeds=4&maxBeds=4&status=U&lastStatus=Sld&minSoldDate=2022-07-01&statistics=avg-soldPrice&listings=false ``` # Supported Statistics Supported statistics enable comprehensive market analysis by providing both central tendencies (averages and medians) and measures of variability (standard deviations and min/max values) across key real estate metrics. ###### Tax Statistics * **`avg-tax`** - The average annual property tax amount across all properties in the dataset * **`med-tax`** - The median annual property tax amount, representing the middle value when all tax amounts are sorted ###### Price Performance * **`pct-aboveBelowList`** - The percentage of properties that sold above or below their listing price, providing insight into market competitiveness ###### Price per Square Foot * **`avg-priceSqft`** - The average price per square foot, calculated by dividing the price by the property's square footage ###### Property Counts * **`cnt-available`** - The total count of properties that were available for sale or lease for a given period * **`cnt-closed`** - The total count of properties that have completed transactions (sold or leased). Despite its name, `cnt-closed` does not always count by closing date: it follows the date filter used in the request. With `minSoldDate` / `maxSoldDate` it counts by `soldDate`; with `minClosedDate` / `maxClosedDate` it counts by `closedDate`. See [Date Filters Determine Which Date Field Statistics Use](#important-date-filters-determine-which-date-field-statistics-use). * **`cnt-new`** - The total count of newly listed properties within the specified timeframe **How we track available (cnt-available) listings:** Some data sources don't tell us when a listing became unavailable—information we need to count how many properties were available during a specific time period. To work around this, we calculate the unavailable date ourselves by watching for when a listing changes from "active" to "unavailable." **The limitation:** This approach only works going forward from when we start monitoring. We can't go back in time to figure out when listings became unavailable before we started tracking them. This means for these particular data sources, available counts are only accurate from the date we began collecting their data onward—we can't provide reliable historical data from before that point. ###### Days on Market Statistics * **`avg-daysOnMarket`** - The average number of days properties stay on the market * **`med-daysOnMarket`** - The median number of days properties remain on the market before selling * **`sum-daysOnMarket`** - The total cumulative days all properties have been on the market * **`min-daysOnMarket`** - The shortest time any property spent on the market * **`max-daysOnMarket`** - The longest time any property spent on the market * **`sd-daysOnMarket`** - The standard deviation of days on market, showing the variability in how long properties stay listed ###### List Price Statistics * **`avg-listPrice`** - The average listing price across all properties * **`med-listPrice`** - The median listing price, representing the middle value of all listing prices * **`sum-listPrice`** - The total sum of all listing prices * **`min-listPrice`** - The lowest listing price in the dataset * **`max-listPrice`** - The highest listing price in the dataset * **`sd-listPrice`** - The standard deviation of listing prices, indicating price variability in the market ###### Sold Price Statistics * **`avg-soldPrice`** - The average sold price across all completed transactions * **`med-soldPrice`** - The median sold price, representing the middle value of all completed transactions * **`sum-soldPrice`** - The total sum of all sold prices * **`min-soldPrice`** - The lowest sold price in the dataset * **`max-soldPrice`** - The highest sold price in the dataset * **`sd-soldPrice`** - The standard deviation of sold prices, showing the variability in final sale prices ###### Maintenance Fee Statistics * **`avg-maintenanceFee`** - The average monthly maintenance fee for properties that have this cost (typically condos and co-ops) * **`med-maintenanceFee`** - The median monthly maintenance fee across applicable properties * **`avg-maintenanceFeePerSqft`** - The average maintenance fee per square foot, providing a normalized comparison metric * **`med-maintenanceFeePerSqft`** - The median maintenance fee per square foot across applicable properties # Grouping Statistics You can group statistics by different time periods to analyze trends. For example, to see how the average sold price has changed month-to-month over the past 2 years, add grp-mth as a comma-separated value to the statistics parameter: ``` https://api.repliers.io/listings?city=New York&minBeds=4&maxBeds=4&status=U&lastStatus=Sld&minSoldDate=2022-07-01&statistics=avg-soldPrice,grp-mth&listings=false ``` The response will include monthly data points: ```json { "statistics": { "soldPrice": { "avg": 823702, "mth": { "2022-07": { "avg": 743897, "count": 13303 }, "2022-08": { "avg": 759084, "count": 25539 }, "2022-09": { "avg": 739097, "count": 22919 }, ... } } } } ``` ###### Which Date Groupings Are Based On Time-based groupings follow the same rule as statistics: the date filter in your request determines the date field used to assign each transaction to a period. With `minSoldDate` / `maxSoldDate`, `grp-mth` and `grp-yr` group by `soldDate` (contract acceptance date); with `minClosedDate` / `maxClosedDate`, they group by `closedDate` (actual closing date). See [Date Filters Determine Which Date Field Statistics Use](#important-date-filters-determine-which-date-field-statistics-use). ### Supported Groupings * grp-day - By day * grp-mth - By month * grp-yr - By year * grp-{x}-days - Rolling statistics, where x is the number of days for each grouping ###### Multiple Groupings You can get multiple groupings in a single request. For example, if you wanted to group statistics by both month and year, you can add both to your request (comma-separated): ``` https://api.repliers.io/listings?city=New York&minBeds=4&maxBeds=4&status=U&lastStatus=Sld&minSoldDate=2022-07-01&statistics=avg-soldPrice,grp-mth,grp-yr&listings=false ``` ###### Rolling Statistics Rolling statistics provide a moving average over a specified period, smoothing out fluctuations to reveal underlying trends. For instance, to get a rolling average of the sold price over 30 days: ``` https://api.repliers.io/listings?city=New York&minBeds=4&maxBeds=4&status=U&lastStatus=Sld&minSoldDate=2022-07-01&statistics=avg-soldPrice,grp-30-days&listings=false ``` # Requesting Multiple Statistics You can request multiple statistics in a single API call. For example, to retrieve both the average sold price and average days on market you can do so by comma-separating the values avg-daysOnMarket and avg-soldPrice in the statistics parameter: ``` https://api.repliers.io/listings?city=New York&minBeds=4&maxBeds=4&status=U&lastStatus=Sld&minSoldDate=2022-07-01&statistics=avg-daysOnMarket,avg-soldPrice,grp-mth&listings=false ``` # Aggregating Statistics Aggregating statistics allows you to compare different segments within your data. To enable aggregation, add &aggregateStatistics=true and specify the field to aggregate by. For instance, to compare average sold prices by neighborhood: ``` https://api.repliers.io/listings?city=New York&minBeds=4&maxBeds=4&status=U&lastStatus=Sld&minSoldDate=2022-07-01&statistics=avg-soldPrice,grp-mth&listings=false&aggregateStatistics=true&aggregates=address.neighborhood ``` The response will be grouped by neighborhood: ```json { "statistics": { "soldPrice": { "avg": 986486, "mth": { "2022-07": { "avg": 949437, "count": 4600, "aggregates": { "address": { "neighborhood": { "Waterfront Communities C1": { "count": 74, "avg": 805367 }, "Waterfront Communities C2": { "count": 60, "avg": 709361 }, ... } } } } } } } } ``` You can aggregate statistics by various fields. For example, to compare sold prices across different property types: ``` https://api.repliers.io/listings?city=New York&minBeds=4&maxBeds=4&status=U&lastStatus=Sld&minSoldDate=2022-07-01&statistics=avg-soldPrice,grp-mth&listings=false&aggregateStatistics=true&aggregates=details.propertyType ``` The response will include data segmented by property type: ```json { "statistics": { "soldPrice": { "avg": 986486, "mth": { "2022-07": { "avg": 949437, "count": 4600, "aggregates": { "details": { "propertyType": { "Detached": { "count": 2526, "avg": 1090041 }, "Condo Apt": { "count": 844, "avg": 696919 }, ... } } } } } } } } ``` # Summary Our real-time market statistics feature empowers you to create insightful data visualizations that help users understand market trends and make informed decisions. By leveraging granular filters, diverse statistics, and powerful aggregation capabilities, you can customize data to suit specific needs. For detailed documentation and further customization options, please refer to our [API Reference](https://docs.repliers.io/reference/getting-started-with-your-api). # What questions does this article answer? * What is the real-time market statistics feature in Repliers? * How do I scope which listings are included in a statistics query? * What is the difference between `soldDate` and `closedDate`, and which one do statistics use? * How do `minSoldDate`/`maxSoldDate` and `minClosedDate`/`maxClosedDate` affect statistics, `cnt-closed`, and monthly/yearly groupings? * How do I request a specific statistic (e.g., average sold price) using the `statistics` parameter? * How can I return only statistics without listing data to speed up responses? * Which statistics (avg, med, min, max, counts, etc.) are available? * How do I group statistics by day, month, year, or rolling periods? * How can I aggregate statistics by fields like neighborhood or property type? * How can I use these statistics to power charts and market analytics in my app?