Datasets API endpoint
Returns suppressed distribution counts over the Airbnb markets dataset, honoring the same filters as search. Facet enum: `country`, `market`, `currency`, `superhost`, `guest_favorite`, `rating_band`, `review_band`, `admin1` (top subdivision), `locality` (settlement), `room_type` (`entire_place`/`private_room`/`hotel`/`shared_room`), `property_type` (Airbnb's canonical listing type from the detail page), `amenities` (each amenity with the count of listings offering it). The `admin1`, `locality`, `room_type`, `property_type` and `amenities` facets stay empty until their enrichment coverage is high enough to be reliable. group_by enum: `country`, `market`, `admin1`, `locality`, `room_type`, `property_type`.
/datasets/airbnb-markets/facetsReturns suppressed distribution counts over the Airbnb markets dataset, honoring the same filters as search. Buckets below the small-cell suppression floor are omitted. It is aggregate-only.
Dataset id enum:
airbnb-marketsQuery parameters:
facet: required facet to aggregate. Allowed values: country, market, currency, superhost, guest_favorite, rating_band, review_band, admin1, locality, room_type, property_type, amenities.group_by: optional aggregate cell dimension. Allowed values: country, market, admin1, locality, room_type, property_type. Defaults to country.country: optional exact ISO-3166-1 alpha-2 country filter, e.g. FR.market: optional exact metro-market filter, max 128 characters.superhost: optional filter to count only Superhost listings.guest_favorite: optional filter to count only Guest Favorite listings (an observed lower bound; the badge under-counts).min_rating: optional minimum listing rating, from 0 through 5.min_review_count: optional minimum listing review count, 0 or greater.active_since: optional freshness filter, an ISO-8601 date (YYYY-MM-DD).min_listings: optional minimum listings per bucket; raises the small-cell suppression floor.Response behavior:
facet is required; unsupported values return the standard invalid params envelope.superhost returns superhost and not_superhost bucket values.guest_favorite returns guest_favorite and not_guest_favorite bucket values. The badge is an observed lower bound, so the guest_favorite count under-counts and not_guest_favorite correspondingly over-counts.rating_band returns bucket values <3, 3-4, 4-4.5, 4.5-4.8, 4.8+.review_band returns bucket values <1, 1-10, 10-50, 50-200, 200+.admin1 (top subdivision), locality (settlement), room_type, property_type and amenities facets are enrichment-derived. admin1/locality come from a reverse-geocode pass; room_type returns bucket values entire_place, private_room, hotel, shared_room, classified from each listing's search-card descriptor; property_type returns Airbnb's finer canonical listing type read from the detail page; amenities returns each amenity (e.g. Wifi, Pool, Free parking on premises, Pets allowed) with the count of listings in the filtered market that offer it (a listing contributes to every amenity it has). Because each covers a growing share of the census, these facets return an empty items array until that coverage is high enough to be reliable, then fill in on their own as coverage grows.50 buckets ordered by descending count.items array (not an error) when no bucket clears the suppression floor.| Field | Filled in, of 1 checked | Values in the sample |
|---|---|---|
| value | 1 | |
| count | 1 | 5,101,926 |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| facet | string | Yes | Facet enum: country, market, currency, superhost, guest_favorite, rating_band, review_band, admin1, locality, room_type, property_type, amenities Allowed values: country, market, currency, superhost, guest_favorite, rating_band, review_band, admin1, locality, room_type, property_type, amenities. | country | |
| group_by | string | No | country | Aggregate cell dimension enum: country, market, admin1, locality, room_type, property_type. Defaults to country Allowed values: country, market, admin1, locality, room_type, property_type. | |
| country | string | No | Exact ISO-3166-1 alpha-2 country filter, e.g. FR | ||
| market | string | No | Exact metro-market filter, max 128 characters | ||
| superhost | boolean | No | Count only Superhost listings | ||
| guest_favorite | boolean | No | Count only Guest Favorite listings (an observed lower bound; the badge under-counts) | ||
| min_rating | number | No | Minimum listing rating, from 0 through 5 | ||
| min_review_count | integer | No | Minimum listing review count, 0 or greater | ||
| active_since | string | No | Freshness filter, an ISO-8601 date (YYYY-MM-DD) | ||
| min_listings | integer | No | Minimum listings per bucket; raises the small-cell suppression floor | ||
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/datasets/airbnb-markets/facets?facet=country&group_by=country&country=us&superhost=true&guest_favorite=true" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"code": 200,
"msg": "OK",
"data": {
"dataset": "airbnb-markets",
"facet": "currency",
"items": [
{
"value": "USD",
"count": 512000
},
{
"value": "EUR",
"count": 388000
},
{
"value": "BRL",
"count": 96000
}
]
}
}Request schema
No body schema
Response schema
#/definitions/datasets.airbnbMarketsFacetResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | datasets.AirbnbMarketFacetResponse | No | ||||
| data.dataset | string | No | Identifier of the dataset queried (`airbnb-markets`). | |||
| data.facet | string | No | Facet that was aggregated. | |||
| data.items | array | No | Facet values with the number of matching records for each. | |||
| data.items[].count | integer | No | Number of listings with this value. | |||
| data.items[].value | string | No | Facet value, for example a country code, market name, currency or room type. | |||
| 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/airbnb-markets/facets?facet=country&group_by=country&country=us&superhost=true&guest_favorite=true" \
-H "x-api-key: $CRAWLORA_API_KEY"