Datasets API endpoint
Use Crawlora's Airbnb Markets Dataset Facets API to search or inspect stored structured datasets as JSON. This page includes request parameters, cURL examples, response schema, validation behavior, credit cost, and a Playground link for testing before integration. Dataset endpoints read indexed records and do not apply proxy routing.
/datasets/airbnb-markets/facetsReturns 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`. Developers commonly use this endpoint for repeatable dataset search, filtering, facets, local business enrichment, analytics, exports, and internal tools that need structured records beyond the limited manual refinement available in the Google Maps app. Authentication uses the x-api-key header, usage is metered with the credit cost shown on this page, and the request does not trigger live scraping or proxy routing.
Request parameters are generated from the active endpoint catalog. Dataset parameters filter, page, facet, or locate stored structured records; they do not configure a live scraper or proxy path.
| 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 | ||
| group_by | string | No | country | Aggregate cell dimension enum: country, market, admin1, locality, room_type, property_type. Defaults to country | |
| 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?country=us&superhost=true&guest_favorite=true" \ -H "x-api-key: $CRAWLORA_API_KEY"
Send your scraping API key in the x-api-key header. Use the console API Keys page to rotate or select the active key.
Endpoint usage is metered in credits. The plan prices, included credits, limits, and overage rates below match the active backend billing configuration.
| Plan | Price | Included credits | Daily cap | Rate limit | Overage |
|---|---|---|---|---|---|
| Free | $0/mo | 2,000 | 500 daily credits | 5/min | No overage |
| Starter | $9/mo | 20,000 | 5,000 daily credits | 15/min | $0.75/1,000 overage credits when enabled |
| Growth | $29/mo | 100,000 | 25,000 daily credits | 45/min | $0.45/1,000 overage credits when enabled |
| Pro | $79/mo | 400,000 | No daily cap | 120/min | $0.30/1,000 overage credits |
| Business | $199/mo | 1,200,000 | No daily cap | 300/min | $0.20/1,000 overage credits |
| Enterprise | $499/mo | 5,000,000 | No daily cap | 1,000/min | $0.12/1,000 overage credits |
This endpoint reads stored indexed dataset records. It does not execute a live upstream Google Maps request, browser session, or proxy-routed scraping job.
- `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+`. - The `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. - Returns up to `50` buckets ordered by descending count. - Returns an empty `items` array (not an error) when no bucket clears the suppression floor. - Does not trigger live scraping. Example response: ```json { "code": 200, "msg": "OK", "data": { "dataset": "airbnb-markets", "facet": "currency", "items": [ { "value": "USD", "count": 512000 }, { "value": "EUR", "count": 388000 }, { "value": "BRL", "count": 96000 } ] } } ```
Crawlora does not silently return invalid dataset search results when filters, pagination, coordinates, or stored record lookups cannot be satisfied.
| Status | Common failure case |
|---|---|
| 400 | Invalid input, missing required parameter, invalid enum, bad coordinate pair, or result window beyond the dataset limit |
| 404 | Requested stored dataset item is not present |
| 429 | Plan or endpoint rate limit exceeded |
| 500 | Internal dataset query or storage error |
When possible, Crawlora returns structured error context so your integration can adjust filters, page size, location inputs, or lookup identifiers.
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 429 | Too Many Requests | #/definitions/app.Response |
| 500 | Internal Server Error | #/definitions/app.Response |
{
"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 | ||||
| data.facet | string | No | ||||
| data.items | array | No | ||||
| data.items[].count | integer | No | ||||
| data.items[].value | string | No | ||||
| msg | string | No | OK |
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?country=us&superhost=true&guest_favorite=true" \
-H "x-api-key: $CRAWLORA_API_KEY"Crawlora is designed for responsible structured public web data workflows. Customers are responsible for using Crawlora in compliance with applicable laws, third-party rights, target-platform rules, and Crawlora terms.
Read Crawlora terms