---
title: "Search the Airbnb markets dataset"
method: GET
path: "/datasets/airbnb-markets/search"
tags: ["Datasets"]
---

# Search the Airbnb markets dataset

`GET /datasets/airbnb-markets/search`

## Request

- Base URL: `https://api.crawlora.net/api/v1`
- URL: `https://api.crawlora.net/api/v1/datasets/airbnb-markets/search`
- Auth: API key in header `x-api-key`

Returns aggregate Airbnb short-term-rental market rollups from the dataset id enum value `airbnb-markets`. Aggregate-only: each row is a market cell, never an individual listing. Thin cells are suppressed. group_by enum: `country`, `market`, `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). Enrichment-derived groupings include a `coverage` object with the number and share of filtered listings carrying that dimension; the 20% minimum gate is not a completeness guarantee, and counts still describe classified rows only. Each cell also carries `median_price_usd`, the median nightly price converted to USD via an approximate dated FX snapshot, for cross-country comparison (combine with `group_by=room_type` for median price by room type); `guest_favorite_pct`, the share of listings carrying the Guest Favorite badge (an observed lower bound, like `superhost_pct`); and `avg_person_capacity`, the average guests a listing sleeps over the detail-page-enriched sample. Sort enum: `listings_desc`, `superhost_pct_desc`, `rating_desc`, `key_asc`. Billing: this search costs 1 credit per record returned, with a minimum of 2 (an empty result costs 2, a full page of 100 costs 100).

## Query parameters

- `group_by` 'country' | 'market' | 'admin1' | 'locality' | 'room_type' | 'property_type'
- `country` string
- `market` string
- `superhost` boolean
- `guest_favorite` boolean
- `min_rating` number
- `min_review_count` integer
- `active_since` string
- `min_listings` integer
- `sort` 'listings_desc' | 'superhost_pct_desc' | 'rating_desc' | 'key_asc'
- `page` integer
- `page_size` integer

## Headers

- `x-api-key` string, required

## Response `200`

OK

- DatasetsAirbnbMarketsSearchResponseDoc
  - `code` integer
  - `data` DatasetsAirbnbMarketSearchResponse
    - `coverage` EsAirbnbDimensionCoverage
      - `coverage_pct` number: Share of the filtered universe with the dimension, from 0 through 100.
      - `covered_listings` integer: Number of filtered listings with the dimension field populated.
      - `dimension` string: Dimension whose field coverage was measured (for example room_type).
      - `meets_threshold` boolean: Whether the existing presentation gate permits buckets for this result.
      - `minimum_coverage_pct` number: Minimum coverage share required before buckets are returned.
      - `total_listings` integer: Number of listings in the filtered universe, including those without the dimension.
    - `dataset` string: Identifier of the dataset queried (`airbnb-markets`).
    - `group_by` string: Dimension the cells are grouped by: `country`, `market`, `admin1`, `locality`, `room_type` or `property_type`.
    - `items` EsAirbnbMarketCell[]: Aggregate market cells on this page, one per group.
      - `avg_person_capacity` number: Average number of guests a listing sleeps, over the sampled listings. Omitted until the sample is large enough.
      - `avg_rating` number: Average listing rating across rated listings. Omitted when the market has too few rated listings.
      - `avg_review_count` number: Average number of reviews per listing.
      - `distinct_hosts` integer: Number of distinct hosts among the sampled listings. Omitted until the sample is large enough.
      - `enriched_listings` integer: Number of listings in the detail-page sample behind the reliable rates. Omitted when no listing has been sampled.
      - `guest_favorite_listings` integer: Number of listings seen with the Guest Favorite badge.
      - `guest_favorite_pct` number: Share of listings seen with the Guest Favorite badge, from 0 to 100. A lower bound, because the badge does not always show.
      - `guest_favorite_pct_enriched` number: Share of sampled listings that are Guest Favorites, from 0 to 100, taken from listing detail pages. Omitted until the sample is large enough.
      - `key` string: Market this row covers: a country code, metro name or other value of the chosen `group_by` dimension.
      - `last_seen` string: Most recent time a listing in this market was seen, in UTC (RFC 3339).
      - `listings` integer: Number of listings in the market.
      - `listings_per_host` number: Sampled listings divided by distinct hosts, a sign of how concentrated hosting is. Omitted until the sample is large enough.
      - `median_price_usd` number: Median nightly price in US dollars, converted with an approximate dated exchange rate. Omitted when too few listings have a price.
      - `rated_listings` integer: Number of listings that have a rating.
      - `superhost_listings` integer: Number of listings seen with the Superhost badge on the search card.
      - `superhost_pct` number: Share of listings seen with the Superhost badge, from 0 to 100. A lower bound, because the badge does not always show.
      - `superhost_pct_enriched` number: Share of sampled listings that are Superhosts, from 0 to 100, taken from listing detail pages. Omitted until the sample is large enough.
    - `min_listings` integer: Minimum number of listings a cell needs to be included.
    - `page` integer: Page number returned.
    - `page_size` integer: Number of items per page.
    - `sort` string: Sort order applied.
    - `total` integer: Total number of cells.
  - `msg` string

## Other responses

- `400`: Bad Request
- `429`: Too Many Requests
- `500`: Internal Server Error

---

[API](https://skmtc.dev/crawlora/apis/crawlora-api.md) · [All operations](https://skmtc.dev/crawlora/apis/crawlora-api/llms.txt) · [OpenAPI document](https://skmtc.dev/crawlora/apis/crawlora-api/revisions/afac9b012a27?raw)