Sign in

v5

latestOpenAPI 3.1.0Proprietary2026-08-031,5423,1505.5 MB
Real Estate

Top-N regions ranked by a metric value in a given month

Returns the top (or bottom) N regions at a geo tier ranked by the value of a metric in a specific month. Useful for answering questions like which metros have the highest home values this quarter or which states have the lowest inventory.

metric must be one of: zhvi, zori, sales_count, inventory, new_listings, days_on_market, market_temperature. When geo_type is metro, the country aggregate row is excluded from the ranking (only RegionType='msa' rows compete).

get/api/v1/real-estate/top/{metric}/{geo_type}

Path parameters

metricstring required

Metric identifier: zhvi, zori, sales_count, inventory, new_listings, days_on_market, market_temperature.

Example:zhvi

Metric identifier: zhvi, zori, sales_count, inventory, new_listings, days_on_market, market_temperature.

geo_typestring required

Geographic tier: national, state, metro, county, city, zip, neighborhood. Must be supported for the chosen metric.

Example:metro

Geographic tier: national, state, metro, county, city, zip, neighborhood. Must be supported for the chosen metric.

Query parameters

monthstring nullable

Month to rank by (YYYY-MM or YYYY-MM-DD). Defaults to the latest month available.

Example:2026-03

Month to rank by (YYYY-MM or YYYY-MM-DD). Defaults to the latest month available.

limitinteger

Number of rows to return (1-50).

Example:10

Number of rows to return (1-50).

orderstring

Sort direction. desc for highest values first (default); asc for lowest values first.

Example:desc

Sort direction. desc for highest values first (default); asc for lowest values first.

Response

Ordered ranking rows with identity columns (RegionID, RegionName, etc) plus each region's metric value for the selected month.

Example response

{
  "data": {
    "metric": "zhvi",
    "geo_type": "metro",
    "month": "2026-03",
    "limit": 10,
    "order": "desc",
    "unit": "USD (typical home value)",
    "label": "Home Value Index (smoothed, seasonally adjusted, 35th-65th percentile tier)",
    "ranking": [
      {
        "rank": 1,
        "RegionID": 394913,
        "RegionName": "San Jose, CA",
        "RegionType": "msa",
        "StateName": "CA",
        "value": 1823450.1
      }
    ],
    "count": 10,
    "dataset_last_modified": "2026-04-16T17:30:00Z"
  },
  "meta": {
    "endpoint": "/api/v1/fred/us/cpi",
    "data_time": "2026-04-16T14:30:00Z",
    "response_time": "2026-04-16T14:30:12Z",
    "provider": "Sugra API v1.0.1",
    "source": "sugra_crypto",
    "attribution": "Short interest and Reg SHO daily short volume data is owned by and sourced from FINRA (Financial Industry Regulatory Authority).",
    "fallback_chain": [
      "sugra_crypto",
      "sugra_finance"
    ]
  }
}