# Airbnb availability calendar (SERP-compatible): `POST /v1/serp/airbnb_property_availability_calendar`

Cost: from 12 credits (12 with the default `price_nights: none`; with `sample` or `all`, plus 1 per night actually priced (at most 92). Failed requests are free). Docs: https://scrapercompany.com/docs/reference/serp-airbnb-calendar

The standard SERP API `airbnb_property_availability_calendar`, field for field.

`property_id`, `start_month`, `start_year`, `months` and `airbnb_domain`
keep the standard SERP API names and defaults, and every day keeps `date`,
`is_available`, `is_available_for_checkin`, `is_available_for_checkout`,
`is_bookable`, `min_nights` and `max_nights`. The standard shape has no prices;
set `price_nights` to add a `price` object to priced days (The standard SERP API Airbnb search price vocabulary). The default `none` costs 12 credits.

Request body (JSON):

- `currency` (string | null; optional; one of AED, AUD, BAM, BGN, BRL, CAD, CHF, CLP, CNY, COP, CRC, CZK, DKK, EGP, EUR, GBP, GHS, GTQ, HKD, HNL, HUF, IDR, ILS, INR, JPY, KES, KRW, KZT, MAD, MXN, MYR, NOK, NZD, PEN, PHP, PLN, QAR, RON, RUB, SAR, SEK, SGD, THB, TRY, TWD, UAH, UGX, USD, UYU, VND, ZAR): Airbnb-supported ISO 4217 currency for quoted prices. Omit for the domain's default; the currency Airbnb actually priced in is returned on every priced day.
- `adults` (integer; optional; default 1; min 1, max 16): Adults aged 13+; quotes are priced for this party.
- `children` (integer; optional; default 0; min 0, max 15): Children aged 2-12.
- `infants` (integer; optional; default 0; min 0, max 5): Infants under 2.
- `pets` (integer; optional; default 0; min 0, max 5): Pets.
- `max_price_quotes` (integer | null; optional; min 1, max 92): Upper bound on price quotes, 1-92. The request holds 8 + this many credits and is charged 8 + the nights actually priced.
- `stay_nights` (integer | null; optional; min 1, max 28): Length of the stay each priced date is quoted for. Omit to use each date's own minimum stay. Airbnb folds cleaning and service fees into its nightly rate, so the same night costs less per night on a longer stay. 1-28.
- `engine` (string; optional; default airbnb_property_availability_calendar): Accepted for SERP API request compatibility; the path already selects the engine.
- `property_id` (string; required; pattern ^\d{1,25}$): Numeric Airbnb listing id: the number in `https://www.airbnb.com/rooms/<id>`, or `properties[].id` from `/v1/serp/airbnb`.
- `start_month` (integer | null; optional; min 1, max 12): SERP API `start_month`: first month, 1-12. Defaults to the current month.
- `start_year` (integer | null; optional; min 2020, max 2100): SERP API `start_year`. Defaults to the current year.
- `months` (integer; optional; default 12; min 1, max 12): SERP API `months`: 1-12, default 12.
- `airbnb_domain` (string; optional; default airbnb.com; one of airbnb.ae, airbnb.am, airbnb.at, airbnb.az, airbnb.ba, airbnb.be, airbnb.ca, airbnb.cat, airbnb.ch, airbnb.cl, airbnb.cn, airbnb.co.cr, airbnb.co.id, airbnb.co.in, airbnb.co.kr, airbnb.co.nz, airbnb.co.uk, airbnb.co.ve, airbnb.com, airbnb.com.ar, airbnb.com.au, airbnb.com.bo, airbnb.com.br, airbnb.com.bz, airbnb.com.co, airbnb.com.ec, airbnb.com.ee, airbnb.com.gt, airbnb.com.hk, airbnb.com.hn, airbnb.com.my, airbnb.com.ni, airbnb.com.pa, airbnb.com.pe, airbnb.com.ph, airbnb.com.py, airbnb.com.ro, airbnb.com.sg, airbnb.com.sv, airbnb.com.tr, airbnb.com.tw, airbnb.com.ua, airbnb.com.vn, airbnb.cz, airbnb.de, airbnb.dk, airbnb.es, airbnb.fi, airbnb.fr, airbnb.gr, airbnb.gy, airbnb.hu, airbnb.ie, airbnb.is, airbnb.it, airbnb.jp, airbnb.lt, airbnb.lu, airbnb.lv, airbnb.me, airbnb.mx, airbnb.nl, airbnb.no, airbnb.pl, airbnb.pt, airbnb.rs, airbnb.ru, airbnb.se, airbnb.si, ar.airbnb.com, bg.airbnb.com, de.airbnb.lu, es.airbnb.com, fr.airbnb.be, fr.airbnb.ca, fr.airbnb.ch, ga.airbnb.ie, he.airbnb.com, hi.airbnb.co.in, hr.airbnb.com, it.airbnb.ch, ka.airbnb.com, kn.airbnb.co.in, mk.airbnb.com, mr.airbnb.co.in, mt.airbnb.com.mt, sk.airbnb.com, sq.airbnb.com, sw.airbnb.com, th.airbnb.com, xh.airbnb.co.za, zh-t.airbnb.com, zh.airbnb.com, zu.airbnb.co.za): Country/language Airbnb host. The host does not change prices; it picks the market and the default currency. `airbnb.ca`, `airbnb.com` and `airbnb.co.uk` all work.
- `price_nights` (string; optional; default none; one of none, sample, all): ScraperCompany addition. Default `none` returns exactly the standard SERP API fields at the base cost. `none`: availability only (one upstream request). `sample`: quote `max_price_quotes` check-in dates spread evenly over the valid ones (default 12). `all`: quote every valid check-in date in order, up to `max_price_quotes` (default and maximum 92). Each quote is one credit.
- `zero_retention` (boolean; optional; default false): Accepted for SERP API compatibility; calendars and quotes are never persisted.

Response fields:

- `search_metadata` (object; required)
  - `search_metadata.id` (string; required)
  - `search_metadata.status` (string; required; one of Success)
  - `search_metadata.created_at` (string; required): UTC, ISO-8601.
  - `search_metadata.request_time_taken` (number; required): Seconds spent in upstream requests, summed; can exceed `total_time_taken` because quotes run in parallel.
  - `search_metadata.parsing_time_taken` (number; required)
  - `search_metadata.total_time_taken` (number; required)
  - `search_metadata.request_url` (string; required): Listing URL.
  - `search_metadata.collection_id` (string; required): Shared by every price in this response (`ratecol_...`).
  - `search_metadata.observed_at` (string; required): UTC observation time, ISO-8601.
  - `search_metadata.upstream_requests` (integer; required): Upstream requests made: 1 for the calendar plus one per quote attempt.
- `search_parameters` (object; required): Echo of the effective request.
  - `search_parameters.engine` (string; required; one of airbnb_property_availability_calendar)
  - `search_parameters.airbnb_domain` (string; required)
  - `search_parameters.property_id` (string; required)
  - `search_parameters.start_month` (integer; required): Effective first month (defaults resolved).
  - `search_parameters.start_year` (integer; required)
  - `search_parameters.months` (integer; required)
  - `search_parameters.currency` (string; optional): Present only when sent.
  - `search_parameters.adults` (integer; optional): Present only when `price_nights` isn't `none`.
  - `search_parameters.children` (integer; optional): Present only when non-zero and `price_nights` isn't `none`.
  - `search_parameters.infants` (integer; optional): Present only when non-zero and `price_nights` isn't `none`.
  - `search_parameters.pets` (integer; optional): Present only when non-zero and `price_nights` isn't `none`.
  - `search_parameters.price_nights` (string; optional; one of sample, all): Present only when not `none`.
  - `search_parameters.max_price_quotes` (integer; optional): As sent. Present only when sent and `price_nights` isn't `none`.
  - `search_parameters.stay_nights` (integer; optional): Present only when sent and `price_nights` isn't `none`.
- `months` (array of object; required): One entry per requested month, in order.
  - `months[].year` (integer; required)
  - `months[].month` (integer; required): 1-12.
  - `months[].days` (array of object; required): In date order.
- `price_summary` (object; optional): Present only when `price_nights` isn't `none`.
  - `price_summary.days` (integer; required): Days returned.
  - `price_summary.available` (integer; required): Days whose night is open.
  - `price_summary.available_for_checkin` (integer; required): Days Airbnb allows arriving on.
  - `price_summary.bookable` (integer; required): Days Airbnb marks bookable.
  - `price_summary.priced` (integer; required): Days with a quoted price (each is charged 1 credit).
  - `price_summary.min_price_per_night` (number; optional): Lowest `price_per_night` among priced days. Present only when at least one day was priced.
  - `price_summary.max_price_per_night` (number; optional): Highest `price_per_night` among priced days. Present only when at least one day was priced.
  - `price_summary.median_price_per_night` (number; optional): Median `price_per_night` among priced days, 2 decimals. Present only when at least one day was priced.
  - `price_summary.price_status` (object; required): Number of days per `price_status` value, keys sorted; only statuses that occur are present.
- `warnings` (array of string; optional): Things worth checking: refused, failed or skipped quotes, a currency other than the one asked for, stays quoted longer than `stay_nights`. Present only when there is at least one.

Base URL: `https://api.scrapercompany.com`. Auth: send your key in the `x-api-key` header. A failed request (4xx or 5xx) or an empty result costs 0 credits.

- [Full API reference as one Markdown file](https://scrapercompany.com/llms-full.txt)
- [OpenAPI spec](https://scrapercompany.com/openapi.json)
