# Airbnb (/docs/airbnb)

Search Airbnb listings with priced stays, then read listing details, guest reviews and availability calendars

Airbnb lists homes and rooms for short stays. These endpoints search a place for priced listings, read one listing in full, page through its guest reviews and read its availability calendar. Listings use the canonical `Place` shape and reviews use the canonical `Review` shape, like Booking.com and Tripadvisor.

Base URL: `/v1/airbnb/...`

Airbnb exposes 4 routes here. Listing routes take exactly one of `id` or `url`.

  A listing id that does not exist answers `503` with a note to check the id, not `404`. The source answers the same way for a missing listing and a brief outage, so the response asks you to confirm the id. That call is never charged.

## Quickstart

### Search a place

Pass `check_in` and `check_out` (YYYY-MM-DD) to price a stay. Without dates the search prices Airbnb's default stay and echoes the dates it used in `data.check_in` and `data.check_out`.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/airbnb/search?location=Lisbon%2C%20Portugal&check_in=2026-12-01&check_out=2026-12-05&adults=2" \
  -H "x-api-key: YOUR_API_KEY"
```

### Read one listing

Take the listing id from a search row. With dates, the listing also prices that stay in `place.hotel.prices`.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/airbnb/listing?id=33579922&check_in=2026-12-01&check_out=2026-12-05" \
  -H "x-api-key: YOUR_API_KEY"
```

### Pull its guest reviews

Reviews come up to 24 a page, in the language the guest wrote them, with the host's reply in `review.responses`. `data.total` is the listing's full review count.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/airbnb/listing/reviews?id=33579922" \
  -H "x-api-key: YOUR_API_KEY"
```

## Availability calendar

`listing/availability` returns a listing's calendar night by night for up to 12 months. Each night says whether it is available and bookable, whether a stay can start or end on it, and the minimum and maximum stay. A closed night that still allows check-out is the last night of someone's booking. Nights beyond the host's own booking window come back unavailable, so a long closed run at the end usually marks the edge of that window.

```bash title="cURL"
curl "https://www.socialcrawl.dev/v1/airbnb/listing/availability?id=33579922&months=6" \
  -H "x-api-key: YOUR_API_KEY"
```

## All endpoints

## Platform notes

**Calendar nights carry no price.** `GET /v1/airbnb/listing` with dates prices a stay.

**Review text keeps the guest's language.** `review.language` names the language of the text, and `review.translated` says whether Airbnb also published a translation.

**Search pages with a cursor.** Pass the returned `cursor` for the next page of up to 18 listings.

## Next steps

- [Credits](/docs/credits.md): What each tier costs, and which failures are refunded.
- [Pagination](/docs/pagination.md): How cursors work across list endpoints.
- [Booking.com](/docs/booking.md): Hotel search with priced rooms and guest reviews.
- [Tripadvisor](/docs/tripadvisor.md): Traveler reviews for places, in the same review shape.