# Airbnb priced calendar: `POST /v1/airbnb/calendar`

Cost: from 12 credits (12, plus 1 per night actually priced (at most 92, so at most 104 a call); refused, failed and unsampled nights and failed requests are free). Docs: https://scrapercompany.com/docs/reference/airbnb-calendar

Day-by-day availability for 1-12 months with Airbnb's own quoted prices.

One upstream call returns availability, min/max nights and check-in /
check-out rules. With `price_nights` = `sample` or `all`, each priced
date is the check-in of a real quoted stay (`stay_nights`, default the
date's minimum stay) from the query the listing page's booking sidebar
runs: the nightly figure, taxes, discounts and total the guest would see.

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.
- `listing_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`.
- `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.
- `months` (integer; optional; default 3; min 1, max 12): Calendar months to return, starting at `start_month` (default 3).
- `start_month` (integer | null; optional; min 1, max 12): First month, 1-12. Defaults to the current month.
- `start_year` (integer | null; optional; min 2020, max 2100): Year of `start_month`. Defaults to the current year.
- `price_nights` (string; optional; default sample; one of none, sample, all): `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.
- `include_listing` (boolean; optional; default false): Add title, property type, rating, capacity and coordinates. No extra credits.

Response fields:

- `listing_id` (string; required): Airbnb listing id.
- `link` (string; required): Listing URL on `airbnb_domain`.
- `airbnb_domain` (string; required)
- `currency` (string; optional): Currency of the quoted prices: the one Airbnb priced in, else the requested `currency`. Omitted when neither is known (no `currency` sent and no day priced).
- `requested_currency` (string; optional): Present only when `currency` was sent.
- `guests` (object; required): Party the quotes were priced for.
  - `guests.adults` (integer; required)
  - `guests.children` (integer; required)
  - `guests.infants` (integer; required)
  - `guests.pets` (integer; required)
- `start_month` (integer; required): Effective first month (defaults to the current UTC month).
- `start_year` (integer; required): Effective year of `start_month`.
- `months` (integer; required)
- `price_nights` (string; required; one of none, sample, all)
- `stay_nights` (integer; optional): Present only when `stay_nights` was sent.
- `max_price_quotes` (integer; required): Quote budget that applied: the requested `max_price_quotes` or the mode default (12 for `sample`, 92 for `all`), capped at 92 and at 31 x `months`; 0 with `price_nights: none`.
- `listing` (object; optional): Present only when at least one listing fact is known.
  - `listing.constant_min_nights` (integer; optional): Minimum stay that applies to every date, when Airbnb reports one.
  - `listing.max_guests` (integer; optional): Guest capacity.
  - `listing.pets_allowed` (boolean; optional)
  - `listing.children_allowed` (boolean; optional)
  - `listing.infants_allowed` (boolean; optional)
  - `listing.guest_policy` (string; optional): Airbnb's guest-policy sentence, e.g. `This place has a maximum of 2 guests, not including infants.`
  - `listing.title` (string; optional): Listing title. Only with `include_listing`.
  - `listing.property_type` (string; optional): Airbnb property type, e.g. `PRIVATE_SUITE`. Only with `include_listing`.
  - `listing.room_type` (string; optional): Airbnb space type, e.g. `ENTIRE_HOME`. Only with `include_listing`.
  - `listing.location` (string; optional): Displayed location, e.g. `Toronto`. Only with `include_listing`.
  - `listing.overview` (array of string; optional): Summary items, e.g. `Entire guest suite`, `1 bed`, `1 bath`. Only with `include_listing`.
  - `listing.rating` (number; optional): Average rating. Only with `include_listing`.
  - `listing.reviews` (integer; optional): Review count. Only with `include_listing`.
  - `listing.is_guest_favorite` (boolean; optional): Only with `include_listing`.
  - `listing.is_luxe` (boolean; optional): Only with `include_listing`.
  - `listing.gps_coordinates` (object; optional): Only with `include_listing`.
- `summary` (object; required): Counts over the returned days, and the spread of quoted nightly prices.
  - `summary.days` (integer; required): Days returned.
  - `summary.available` (integer; required): Days whose night is open.
  - `summary.available_for_checkin` (integer; required): Days Airbnb allows arriving on.
  - `summary.bookable` (integer; required): Days Airbnb marks bookable.
  - `summary.priced` (integer; required): Days with a quoted price (each is charged 1 credit).
  - `summary.min_price_per_night` (number; optional): Lowest `price_per_night` among priced days. Present only when at least one day was priced.
  - `summary.max_price_per_night` (number; optional): Highest `price_per_night` among priced days. Present only when at least one day was priced.
  - `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.
  - `summary.price_status` (object; required): Number of days per `price_status` value, keys sorted; only statuses that occur are present.
- `days` (array of object; required): One row per date of the requested months, in date order.
  - `days[].date` (string (date); required): Calendar date; the night starts on this date.
  - `days[].available` (boolean; required): The night is open (not booked or blocked).
  - `days[].available_for_checkin` (boolean; required): Airbnb allows arriving on this date.
  - `days[].available_for_checkout` (boolean; required): Airbnb allows departing on this date.
  - `days[].bookable` (boolean; required): Airbnb's bookable flag for this date.
  - `days[].min_nights` (integer; optional): Minimum stay for a check-in on this date. Present only when Airbnb reports it.
  - `days[].max_nights` (integer; optional): Maximum stay for a check-in on this date. Present only when Airbnb reports it.
  - `days[].closed_to_arrival` (boolean; optional): Arrival restriction for this date. Present only when Airbnb returns arrival/departure rules for it.
  - `days[].closed_to_departure` (boolean; optional): Departure restriction for this date. Present only when Airbnb returns arrival/departure rules for it.
  - `days[].price_status` (object; optional; one of priced, not_sampled, quote_cap_reached, not_requested, unavailable, past, check_in_not_allowed, check_out_not_allowed, stay_blocked, stay_exceeds_max_nights, quote_refused, no_price, quote_failed, quote_skipped): Present unless `price_nights` is `none`.
  - `days[].price_error` (string; optional): Reason behind `quote_refused` (Airbnb's message), `no_price`, `quote_failed` or `quote_skipped` (`deadline_exceeded` or `stopped_after_failures`). Present only when there is one.
  - `days[].price` (object; optional): Present only when `price_status` is `priced`.
- `metadata` (object; required)
  - `metadata.collection_id` (string; required): Shared by every price in this response (`ratecol_...`).
  - `metadata.observed_at` (string; required): UTC observation time, ISO-8601.
  - `metadata.upstream_requests` (integer; required): Upstream requests made, including retried attempts.
  - `metadata.price_quotes` (integer; required): Stays planned for quoting (skipped quotes included).
  - `metadata.request_time_taken` (number; required): Seconds spent in upstream requests, summed. Quotes run in parallel, so this can exceed `total_time_taken`.
  - `metadata.parsing_time_taken` (number; required): Seconds spent parsing the calendar.
  - `metadata.total_time_taken` (number; required): End-to-end seconds for this request.
- `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`, missing listing details. 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)
