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). Enrichment-derived facets include a `coverage` object with the number and share of filtered listings carrying that dimension; buckets stay empty below the 20% minimum visibility gate. Coverage above the gate may still be partial. 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 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). For a filtered universe of at least 50 listings, these facets include a coverage object with the number of filtered listings carrying the field, the filtered-universe denominator, coverage_pct, the 20% minimum visibility threshold, and meets_threshold. Below the threshold, items is empty but coverage reports the gap. Below the 50-listing suppression floor, both items and coverage are omitted so small-cell totals are not disclosed. Above it, bucket counts still describe only rows carrying the dimension; the threshold is not a completeness guarantee.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": "room_type",
"coverage": {
"dimension": "room_type",
"covered_listings": 294,
"total_listings": 1000,
"coverage_pct": 29.4,
"minimum_coverage_pct": 20,
"meets_threshold": true
},
"items": [
{
"value": "entire_place",
"count": 244
},
{
"value": "private_room",
"count": 50
}
]
}
}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.coverage | object | No | Coverage over the filtered listing universe for enrichment-derived facets. Omitted for facets that do not depend on a partial field. | |||
| data.coverage.coverage_pct | number | No | Share of the filtered universe with the dimension, from 0 through 100. | |||
| data.coverage.covered_listings | integer | No | Number of filtered listings with the dimension field populated. | |||
| data.coverage.dimension | string | No | Dimension whose field coverage was measured (for example room_type). | |||
| data.coverage.meets_threshold | boolean | No | Whether the existing presentation gate permits buckets for this result. | |||
| data.coverage.minimum_coverage_pct | number | No | Minimum coverage share required before buckets are returned. | |||
| data.coverage.total_listings | integer | No | Number of listings in the filtered universe, including those without the dimension. | |||
| 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"