openapi: 3.0.0 info: title: Airbnb Property Availability Calendar API description: | Retrieve the day-by-day booking calendar for an Airbnb property — including which dates are available, bookable, and the minimum / maximum stay constraints. Returns up to 12 months of data starting from a configurable month/year. **Cross-linking**: The `property_id` parameter required by this API is obtained from the Airbnb Search API or Airbnb Property API. version: 1.0.0 servers: - url: https://www.searchapi.io/api/v1 paths: /search: get: summary: Airbnb Property Availability Calendar security: - ApiKeyAuth: [] - ApiKeyQuery: [] parameters: - name: engine in: query required: true description: Set to `airbnb_property_availability_calendar` for this API. schema: type: string enum: ["airbnb_property_availability_calendar"] default: "airbnb_property_availability_calendar" - name: property_id in: query required: true description: Airbnb property ID. Obtained from Airbnb Search or Property API results, or from Airbnb URLs (`https://www.airbnb.com/rooms/{property_id}`). schema: type: string - name: start_month in: query required: false description: Starting month of the calendar window (1-12). Defaults to the current month. schema: type: integer minimum: 1 maximum: 12 - name: start_year in: query required: false description: Starting year of the calendar window (4-digit year). Defaults to the current year. schema: type: integer minimum: 1970 maximum: 2100 - name: months in: query required: false description: Number of months to retrieve starting from `start_month` / `start_year`. Must be between 1 and 12. schema: type: integer minimum: 1 maximum: 12 default: 12 - name: airbnb_domain in: query required: false description: Airbnb domain to use. Affects regional handling. schema: type: string enum: ["airbnb.com", "sw.airbnb.com", "sq.airbnb.com", "ar.airbnb.com", "airbnb.com.ar", "airbnb.am", "airbnb.com.au", "airbnb.at", "airbnb.az", "airbnb.be", "fr.airbnb.be", "airbnb.com.bz", "airbnb.com.bo", "airbnb.ba", "airbnb.com.br", "bg.airbnb.com", "airbnb.ca", "fr.airbnb.ca", "airbnb.cl", "airbnb.cn", "airbnb.com.co", "airbnb.co.cr", "hr.airbnb.com", "airbnb.cz", "airbnb.dk", "airbnb.com.ec", "airbnb.com.sv", "airbnb.com.ee", "airbnb.fi", "airbnb.fr", "ka.airbnb.com", "airbnb.de", "airbnb.gr", "airbnb.com.gt", "airbnb.gy", "airbnb.com.hn", "airbnb.com.hk", "airbnb.hu", "airbnb.is", "airbnb.co.in", "hi.airbnb.co.in", "kn.airbnb.co.in", "mr.airbnb.co.in", "airbnb.co.id", "airbnb.ie", "ga.airbnb.ie", "he.airbnb.com", "airbnb.it", "airbnb.jp", "airbnb.lv", "airbnb.lt", "airbnb.lu", "de.airbnb.lu", "airbnb.com.my", "mt.airbnb.com.mt", "airbnb.mx", "airbnb.me", "airbnb.nl", "airbnb.co.nz", "airbnb.com.ni", "mk.airbnb.com", "airbnb.no", "airbnb.com.pa", "airbnb.com.py", "airbnb.com.pe", "airbnb.com.ph", "airbnb.pl", "airbnb.pt", "airbnb.com.ro", "airbnb.ru", "airbnb.rs", "airbnb.com.sg", "sk.airbnb.com", "airbnb.si", "xh.airbnb.co.za", "zu.airbnb.co.za", "airbnb.co.kr", "airbnb.cat", "airbnb.es", "airbnb.se", "fr.airbnb.ch", "airbnb.ch", "it.airbnb.ch", "airbnb.com.tw", "th.airbnb.com", "airbnb.com.tr", "airbnb.com.ua", "airbnb.ae", "airbnb.co.uk", "zh.airbnb.com", "zh-t.airbnb.com", "es.airbnb.com", "airbnb.co.ve", "airbnb.com.vn"] default: "airbnb.com" responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/CalendarResponse' '400': description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Authentication Error. The API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate Limit Exceeded. The number of allowed requests has been exceeded. Consider upgrading your plan or waiting for the limit to reset. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Server Error. Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Timeout. We could not retrieve results in 90 seconds. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"' ApiKeyQuery: type: apiKey in: query name: api_key description: Pass API key as query parameter schemas: CalendarResponse: type: object properties: search_metadata: $ref: '#/components/schemas/SearchMetadata' search_parameters: $ref: '#/components/schemas/SearchParameters' months: type: array description: Calendar months returned for the requested window. Each item contains the year, month, and per-day availability. items: $ref: '#/components/schemas/CalendarMonth' error: type: string description: Error message returned when no calendar data can be retrieved. SearchMetadata: type: object required: [id, status, created_at] properties: id: type: string description: Unique identifier for the search request status: type: string description: Status of the search request created_at: type: string format: date-time description: Timestamp when the search was created request_time_taken: type: number description: Time taken to make the request in seconds parsing_time_taken: type: number description: Time taken to parse the results in seconds total_time_taken: type: number description: Total time taken for the search in seconds request_url: type: string description: Airbnb URL for this search html_url: type: string description: URL to view HTML results json_url: type: string description: URL to view JSON results SearchParameters: type: object properties: engine: type: string description: The engine used for this search airbnb_domain: type: string description: The Airbnb domain used for this search property_id: type: string description: The property ID used for this search start_month: type: integer description: The starting month used for this search start_year: type: integer description: The starting year used for this search months: type: integer description: The number of months requested CalendarMonth: type: object properties: year: type: integer description: 4-digit year of this calendar month month: type: integer description: Month number (1-12) days: type: array description: One entry per day of the month. items: $ref: '#/components/schemas/CalendarDay' CalendarDay: type: object properties: date: type: string description: Date in `YYYY-MM-DD` format is_available: type: boolean description: Whether the date is available on the calendar (not blocked by the host) is_available_for_checkin: type: boolean description: Whether a guest can check in on this date is_available_for_checkout: type: boolean description: Whether a guest can check out on this date is_bookable: type: boolean description: Whether the date can be the starting day of a booking (passes all stay-length and check-in constraints) min_nights: type: integer description: Minimum number of nights required for a booking starting on this date max_nights: type: integer description: Maximum number of nights allowed for a booking starting on this date ErrorResponse: type: object required: [error] properties: error: type: string description: Error message describing what went wrong