Airbnb

GET
# Destination Search API

Get Airbnb listing cards for a destination, one page of 18 at a time (pages 1–15). Use a city, neighborhood, or postal code, not a listing title: native property-name lookup is not available.

## Overview

### Endpoint URL

GET https://api.stayapi.com/v1/airbnb/search 

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| location | string | Required | Trimmed, 2–200 characters: a city, neighborhood, or postal code such as `30308`, `Atlanta-GA-30308`, or `SW1A 1AA`. |
| check\_in / check\_out | date | Optional | Paired, ordered `YYYY-MM-DD` dates. |
| adults | integer | Optional | Defaults to 1 (1–16). |
| children | integer | Optional | Defaults to 0 (0–16). |
| infants / pets | integer | Optional | Default to 0 (0–5). |
| currency | string | Optional | Defaults to USD. |
| page | integer | Optional | Defaults to 1 (1–15). Airbnb shows 18 listings per page. |

## Pagination and large areas

Airbnb returns at most 15 pages (about 270 listings) for any one search. Request `page` 1 first, then keep requesting the next page while `has_next_page` is `true`. Each page is a separate request. A page past the last one returns an empty `listings` list with `has_next_page: false`.

To collect more listings for a whole city, run the search for each of its postal codes and page through each one. Results are centered on the location rather than strictly bounded by it, and ranking can shift between requests, so pages and neighboring areas can overlap: deduplicate by `listing_id`.

## Response scope

The response contains `location`, `requested_currency`, optional dates, `dates_requested`, `availability_verified` (always `false`), `page`, `total_pages` (0 when nothing matched), `has_next_page`, `count`, and `listings`. The older `page_scope` field is deprecated: it is `first_page` on page 1 and `later_page` on later pages; use `page` instead.

Each listing includes `listing_id`, `url`, and `title`, with optional `name`, `image_url`, `rating_display`, `displayed_price`, `price_qualifier`, `price_currency`, and `price_applies_to_requested_dates`.

Undated searches omit prices. A dated displayed price is returned only when it applies to the requested dates and guests; neither mode confirms availability.

USD is set only when the rendered price explicitly carries a `USD` suffix; `€` and `£` map to EUR and GBP. Other display formats leave `price_currency` null.

## Errors

Invalid requests, including a `page` outside 1–15, return 400 or 422 Problem Details. Upstream failures return 502, 503, or 504; do not treat those as empty results.

Request

```curl
curl 'https://api.stayapi.com/v1/airbnb/search?location=Paris%2C+France&check_in=2026-11-01&check_out=2026-11-04&adults=2&currency=USD&page=2' -H 'X-API-Key: YOUR_API_KEY'
```

Response

```json
{
  "location": "Paris, France",
  "requested_currency": "USD",
  "check_in": "2026-11-01",
  "check_out": "2026-11-04",
  "dates_requested": true,
  "availability_verified": false,
  "page": 2,
  "total_pages": 15,
  "has_next_page": true,
  "page_scope": "later_page",
  "count": 1,
  "listings": [{
    "listing_id": "<Airbnb listing ID>",
    "url": "https://www.airbnb.com/rooms/<Airbnb listing ID>",
    "title": "Example listing title",
    "displayed_price": "$423 USD",
    "price_currency": "USD",
    "price_applies_to_requested_dates": true
  }]
}
```

```json
{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "Invalid request parameters",
  "instance": "/v1/airbnb/search",
  "provider": "airbnb"
}
```
