Datasets API endpoint
Returns terms aggregation counts for the housing markets dataset. Facet enum: `region_type`, `state_code`, `property_type`, `parent_metro`, `parent_metro_code`, `income_vintage`, `is_latest`, `period_begin`. region_type enum: `national`, `metro`, `county`, `city`, `zip`. property_type enum: `All Residential`, `Single Family Residential`, `Condo/Co-op`, `Townhouse`, `Multi-Family (2-4 Unit)`, `Single Units Only`.
/datasets/housing-markets/facetsReturns terms aggregation counts over the US housing markets dataset, honoring the same filters as search.
Dataset id enum:
housing-marketsQuery parameters:
facet: required facet to aggregate. Allowed values: region_type, state_code, property_type, parent_metro, parent_metro_code, income_vintage, is_latest, period_begin.q: optional full-text query over region name and city, max 256 characters.region_type: optional region level. Allowed values: national, metro, county, city, zip.state_code: optional exact two-letter state code filter, e.g. CA.property_type: optional property type. Allowed values: All Residential, Single Family Residential, Condo/Co-op, Townhouse, Multi-Family (2-4 Unit), Single Units Only.parent_metro_code: optional exact parent metro (CBSA) code filter.zip_code: optional exact zip code filter (zip-level rows only).period: optional exact period start date filter, YYYY-MM-DD.latest: optional; true keeps only the most recent period per region and property type.min_median_sale_price / max_median_sale_price: optional median sale price bounds in USD.min_median_list_price / max_median_list_price: optional median list price bounds in USD.min_price_to_income / max_price_to_income: optional price-to-income ratio bounds.min_salary_to_buy / max_salary_to_buy: optional salary-to-buy bounds, USD per year.min_median_dom / max_median_dom: optional median days-on-market bounds.min_inventory / max_inventory: optional active-inventory bounds.min_homes_sold: optional minimum homes sold in the period.Response behavior:
50 buckets ordered by descending count.facet is required; unsupported values return the standard invalid params envelope.is_latest boolean facet returns true/false bucket values; period_begin buckets are dates.latest=true with the period_begin facet to confirm the dataset's current month, or facet state_code filtered to region_type=city to see per-state city coverage.items array (not an error) when the dataset has no data yet.| Field | Filled in, of 6 checked | Values in the sample |
|---|---|---|
| value | 6 | |
| count | 6 | 173 to 6,345,618, median 1,739,253 |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| facet | string | Yes | Facet enum: region_type, state_code, property_type, parent_metro, parent_metro_code, income_vintage, is_latest, period_begin Allowed values: region_type, state_code, property_type, parent_metro, parent_metro_code, income_vintage, is_latest, period_begin. | region_type | |
| q | string | No | Full-text query over region name and city, max 256 characters | ||
| region_type | string | No | Region level enum: national, metro, county, city, zip Allowed values: national, metro, county, city, zip. | ||
| state_code | string | No | Exact two-letter state code filter, e.g. CA | ||
| property_type | string | No | Property type enum: All Residential, Single Family Residential, Condo/Co-op, Townhouse, Multi-Family (2-4 Unit), Single Units Only | ||
| parent_metro_code | string | No | Exact parent metro (CBSA) code filter, e.g. 16980 | ||
| zip_code | string | No | Exact zip code filter (zip-level rows only), e.g. 60616 | ||
| period | string | No | Exact period start date filter, YYYY-MM-DD | ||
| latest | boolean | No | Filter for the most recent period per region and property type | ||
| min_median_sale_price | number | No | Minimum median sale price in USD | ||
| max_median_sale_price | number | No | Maximum median sale price in USD | ||
| min_median_list_price | number | No | Minimum median list price in USD | ||
| max_median_list_price | number | No | Maximum median list price in USD | ||
| min_price_to_income | number | No | Minimum price-to-income ratio | ||
| max_price_to_income | number | No | Maximum price-to-income ratio | ||
| min_salary_to_buy | integer | No | Minimum salary needed to buy in USD per year | ||
| max_salary_to_buy | integer | No | Maximum salary needed to buy in USD per year | ||
| min_median_dom | number | No | Minimum median days on market | ||
| max_median_dom | number | No | Maximum median days on market | ||
| min_inventory | integer | No | Minimum active inventory | ||
| max_inventory | integer | No | Maximum active inventory | ||
| min_homes_sold | integer | No | Minimum homes sold in the period | ||
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/datasets/housing-markets/facets?facet=region_type&q=coffee®ion_type=national&latest=true" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"dataset": "housing-markets",
"facet": "property_type",
"items": [
{
"value": "All Residential",
"count": 3712450
},
{
"value": "Single Family Residential",
"count": 3689121
},
{
"value": "Condo/Co-op",
"count": 2418804
}
]
}
}Request schema
No body schema
Response schema
#/definitions/datasets.housingMarketsFacetResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | datasets.HousingFacetResponse | No | ||||
| data.dataset | string | No | ||||
| data.facet | string | No | ||||
| data.items | array | No | ||||
| data.items[].count | integer | No | ||||
| data.items[].value | string | No | ||||
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 429 | Too Many Requests | #/definitions/app.Response |
| 500 | Internal Server Error | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/datasets/housing-markets/facets?facet=region_type&q=coffee®ion_type=national&latest=true" \
-H "x-api-key: $CRAWLORA_API_KEY"