This API collection is specific for the stay part of the connected trip. Use these endpoints to search for stays such as hotels and apartments, check availability, retrieve reviews, and get detailed property information.
openapi: 3.1.0
info:
title: Booking.com Demand Accommodations API
version: '3.1'
summary: "The Booking.com Demand API enables Affiliate Partners to access Booking.com's travel inventory, including accommodations, car rentals, and flights. \n\nUse Demand API to search, retrieve details, check availability, manage bookings and run reports using orders details.\n\n- RESTful API with JSON responses.\n- Make HTTPS POST requests to interact with endpoints.\n- Requires authentication using your Affiliate ID and token credentials.\n\n[Check the try out guide!](/demand/docs/getting-started/try-out-the-api)\n"
x-last-validated: '2026-06-02'
x-generated-from: documentation
description: This API collection is specific for the stay part of the connected trip. </br></br>Use these endpoints to search for stays such as hotels and apartments, check availability, retrieve reviews, and get detailed property information.
servers:
- url: https://demandapi.booking.com/3.1
description: Production environment
- url: https://demandapi-sandbox.booking.com/3.1
description: Sandbox environment
security:
- BearerAuth: []
tags:
- name: Accommodations
x-displayName: Accommodation
description: This API collection is specific for the stay part of the connected trip. </br></br>Use these endpoints to search for stays such as hotels and apartments, check availability, retrieve reviews, and get detailed property information.
paths:
/accommodations/search:
post:
summary: Booking.com Search Accommodation
description: This endpoint returns, by default, the cheapest available product for each accommodation that matches the specified search criteria. <br/><br/>When you apply location filters using parameters such as country or region id, the results are sorted by Booking.com popularity (top_picks) instead of price.<br/>In this case, accommodations are ranked in descending order of popularity, meaning higher-ranked listings will appear earlier in the response.
operationId: accommodationsSearch
parameters:
- in: header
name: X-Affiliate-Id
schema:
type: integer
required: true
description: Include here your Affiliate identifier number
tags:
- Accommodations
requestBody:
content:
application/json:
schema:
title: AccommodationsSearchInput
type: object
properties:
24_hour_reception:
description: Filter the result based if the front desk reception is available 24/7. When specified true, the result will filter the products where front desk is available 24/7.
type: boolean
accommodation_facilities:
type: array
items:
description: 'A signed integer number that uniquely identifies an accommodation property facility. Examples of facilities are: Parking, Restaurant, Room service etc. The full list can be obtained by calling <a href="/demand/docs/open-api/demand-api/accommodations/accommodations/constants" target="_blank">accommodations/constants</a>.'
type: integer
minimum: 1
accommodation_types:
type: array
items:
description: 'A signed integer number that uniquely identifies an accommodation property type. Examples of accommodation types are: Apartment, Hostel, Hotel etc. The full list can be obtained by calling <a href="/demand/docs/open-api/demand-api/accommodations/accommodations/constants" target="_blank">accommodations/constants</a>.'
type: integer
minimum: 1
accommodations:
type: array
items:
description: A signed integer number that uniquely identifies an accommodation property. The full list can be obtained by calling [accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details).
type: integer
minimum: 1
maxItems: 100
airport:
description: A three-letter code that uniquely identifies an airport as defined by the International Air Transport Association (IATA). The full list can be obtained by calling <a href="/demand/docs/open-api/demand-api/commonlocations/common/locations/airports" target="_blank">common/locations/airports</a>.
type: string
pattern: ^[A-Z]{3}$
example: AMS
booker:
title: Booker
description: The booker's information.
type: object
properties:
country:
description: The booker country for showing the best price for that user and obeying laws regarding the display of taxes and fees.
type: string
pattern: ^[a-z]{2}$
platform:
description: The booker platform for showing the platform based deals and prices.
type: string
enum:
- android
- desktop
- ios
- mobile
- tablet
state:
description: The booker state for showing the best price for that user and obeying laws regarding the display of taxes and fees. Currently applicable only for country US.
type: string
pattern: ^[a-z]{2}$
travel_purpose:
description: The travel purpose of the booker.
type: string
enum:
- business
- leisure
user_groups:
description: The user groups that the booker is a member of.
type: array
items:
type: string
enum:
- authenticated
required:
- country
- platform
brands:
type: array
items:
description: 'A signed integer number that uniquely identifies an accommodation brand. Examples of brands are: Radisson Blu, WestCord Hotels, Westin etc. The full list can be obtained by calling <a href="/demand/docs/open-api/demand-api/accommodations/accommodations/chains" target="_blank">/accommodations/chains</a>.'
type: integer
minimum: 1
cancellation_type:
description: Filters the result for the cancellation type specified. Possible values are free_cancellation & non_refundable. If cancellation_type is free_cancellation, the result will contain all the products with free_cancellation.
type: string
enum:
- free_cancellation
- non_refundable
checkin:
description: The checkin date. Must be within 500 days in the future and in the format yyyy-mm-dd.
type: string
format: date
checkout:
description: The checkout date. Must be later than {checkin}. Must be between 1 and 90 days after {checkin}. Must be within 500 days in the future and in the format yyyy-mm-dd.
type: string
format: date
city:
description: A signed integer number that uniquely identifies a city. The full list can be obtained by calling <a href="/demand/docs/open-api/demand-api/commonlocations/common/locations/cities" target="_blank">common/locations/cities</a>.
type: integer
coordinates:
title: AccommodationsSearchCoordinatesOutput
description: Limit the result list to the specified coordinates.
type: object
properties:
latitude:
description: Specify a latitude (as well as a longitude and radius) to do searches around a specific location.
type: number
format: double
longitude:
description: Specify a longitude (as well as a latitude and radius) to do searches around a specific location.
type: number
format: double
radius:
description: The radius is km to search around the specified latitude and longitude.
type: number
format: double
country:
description: 'A two-letter code that uniquely identifies a country. This code is defined by the ISO 3166-1 alpha-2 standard (ISO2) as described here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. The full list can be obtained by calling <a href="/demand/docs/open-api/demand-api/commonlocations/common/locations/countries" target="_blank">common/locations/countries</a>.'
type: string
pattern: ^[a-z]{2}$
example: nl
currency:
description: A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling <a href="/demand/docs/open-api/demand-api/commonpayments/common/payments/currencies" target="_blank">common/payments/currencies</a>.
type: string
pattern: ^[A-Z]{3}$
example: EUR
district:
description: A signed integer number that uniquely identifies a district. Typically, districts define known areas within a city. The full list can be obtained by calling <a href="/demand/docs/open-api/demand-api/commonlocations/common/locations/districts" target="_blank">common/locations/districts</a>.
type: integer
minimum: 1
dormitories:
description: This parameter specifies if the results should include dormitory beds or rooms. The default behaviour will include the dormitory beds or rooms with other results. When this flag is set to 'only', the response will only include dormitory beds or rooms. When this flag is set to 'exclude', the response will exclude dormitory beds or rooms. When this flag is set to 'include', the response will include dormitory beds or rooms with other results.
type: string
default: include
enum:
- include
- exclude
- only
extras:
description: Input parameter to request for additional information about the products.
type: array
items:
type: string
enum:
- extra_charges
- products
guests:
title: AccommodationsGuests
description: The guest details for the request.
type: object
properties:
allocation:
description: The exact allocation of guests to rooms.
type: array
items:
properties:
children:
description: The children ages for this room.
type: array
items:
type: integer
minimum: 0
maximum: 17
number_of_adults:
description: The number of adults for this room.
type: integer
minimum: 1
required:
- number_of_adults
children:
description: Array with the children ages.
type: array
items:
type: integer
minimum: 0
maximum: 17
number_of_adults:
description: The number of adults for the search.
type: integer
minimum: 1
number_of_rooms:
description: The number of rooms needed.
type: integer
minimum: 1
required:
- number_of_adults
- number_of_rooms
landmark:
description: A signed integer number that uniquely identifies a relevant geographical landmark, like a monument or a natural attraction. The full list can be obtained by calling <a href="/demand/docs/open-api/demand-api/commonlocations/common/locations/landmarks" target="_blank">common/locations/landmarks</a>.
type: integer
minimum: 1
meal_plan:
description: 'Filter the result based on the selected meal plan. Example: When specified breakfast_included, it will show the product with free breakfast.'
type: string
enum:
- all_inclusive
- breakfast_included
- full_board
- half_board
page:
description: Pagination token used to retrieve the next page of results. Obtained from `next_page`.
type: string
payment:
description: The payment filter for the request
type: object
properties:
credit_card_required:
description: Filter to show accommodations which require credit card
type: boolean
timing:
description: This parameter specifies that the results should only return accommodation and blocks that contain the specified payment timings.
type: string
enum:
- pay_at_the_property
- pay_online
price:
description: If specified, will return only results where the price *per night* falls in the specified range (inclusive). This filter requires that a currency is passed
type: object
properties:
maximum:
description: Set the maximum price per night, in the specified currency, or omit to indicate no upper limit.
type: integer
minimum:
description: Set the minimum price per night, in the specified currency, or omit to indicate no lower limit.
type: integer
rating:
description: The rating filter for the request
type: object
properties:
minimum_review_score:
description: Show only hotels with review_score >= that. Review score should be in the range 1 to 10.
type: integer
minimum: 0
maximum: 10
stars:
description: Limit to accommodations with the given number(s) of stars. Stars should be in the range of 1 to 5.
type: array
items:
type: number
minimum: 1
maximum: 5
region:
description: A signed integer number that uniquely identifies a geographical region. Regions usually define official administrative areas within a country, but may also include multiple countries and in some cases un-official but popular designations for geographical areas. An example of a region that crosses multiple countries is the Alps in Europe. The full list can be obtained by calling <a href="/demand/docs/open-api/demand-api/commonlocations/common/locations/regions" target="_blank">common/locations/regions</a>.
type: integer
minimum: 1
room_facilities:
type: array
items:
description: 'A signed integer number that uniquely identifies an accommodation property room facility. Examples of facilities are: Coffee/Tea maker, TV, Airconditioning, etc. The full list can be obtained by calling <a href="/demand/docs/open-api/demand-api/accommodations/accommodations/constants" target="_blank">accommodations/constants</a>.'
type: integer
minimum: 1
rows:
description: The maximum number of results to return.
type: integer
multipleOf: 10
minimum: 10
maximum: 100
default: 100
sort:
description: The sorting parameters for the response
type: object
properties:
by:
description: 'The way to sort your results. NOTE: When ordering by distance please make sure to specify the latitude and longitude!'
type: string
enum:
- distance
- price
- review_score
- stars
direction:
description: The direction you wish for your sort.by parameter to be sorted in
type: string
enum:
- ascending
- descending
travel_proud:
description: Filter the result based on if the property is LGBTQ+ friendly. When specified true, the result will filter and return only the accommodations that are Proud Certified.
type: boolean
required:
- booker
- checkin
- checkout
- guests
example:
booker:
country: nl
platform: desktop
checkin: '!START_DATE!'
checkout: '!END_DATE!'
city: -2140479
extras:
- extra_charges
- products
guests:
number_of_adults: 2
number_of_rooms: 1
responses:
'200':
description: Successful response.
content:
application/json:
schema:
title: AccommodationsSearchOutput
type: object
properties:
request_id:
description: Uniquely identifies the request. Please provide this identifier when contacting support.
type: string
data:
type: array
items:
title: AccommodationsSearchDataOutput
description: ''
type: object
properties:
id:
description: A signed integer number that uniquely identifies an accommodation property. The full list can be obtained by calling [accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details).
type: integer
minimum: 1
commission:
title: AccommodationsCommission
description: Commission details for the partner for a given accommodation
type: object
properties:
amount:
description: The actual commission amount for the partner.
type: number
format: double
minimum: 0
percentage:
description: Percentage of the fee that will be received as commission.
type: number
format: double
minimum: 0
currency:
description: A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling <a href="/demand/docs/open-api/demand-api/commonpayments/common/payments/currencies" target="_blank">common/payments/currencies</a>.
type: string
pattern: ^[A-Z]{3}$
example: EUR
deep_link_url:
description: A mobile app URL that directs the user to a specific page or content within the Booking.com app. The link can only be used on a device with the Booking.com app installed. It typically includes an Affiliate ID (AID) to attribute bookings to the affiliate partner when users are redirected
type: string
format: url
price:
title: AccommodationsSearchProductPrice
description: The price components of this product or selection of products. 'base' and 'extra_charges' are returned only when explicitly requested (via 'extras=extra_charges').
type: object
properties:
base:
description: The base price. It does not include any extra charges.
type: number
format: double
multipleOf: 0.01
exclusiveMinimum: 0
book:
description: The display price that must be shown to the traveller under local booker protection laws. This price includes the base accommodation cost and all charges that are legally required to be part of the displayed price. Equivalent to base + included charges.
type: number
format: double
multipleOf: 0.01
exclusiveMinimum: 0
extra_charges:
title: AccommodationsExtraCharges
description: The charge breakdown. Includes taxes and fees.
type: object
properties:
excluded:
description: Charges not included in 'book'.
type: number
format: double
minimum: 0
included:
description: Charges included in 'book'.
type: number
format: double
minimum: 0
total:
description: The total price. Includes all extra charges.
type: number
format: double
multipleOf: 0.01
exclusiveMinimum: 0
products:
type: array
items:
title: AccommodationsSearchProductOutput
description: Details product information. It requires `{"extras":["products"]}`.
type: object
properties:
id:
description: Unique ID of the product.
type: string
bundle:
description: The bundle ID of the product comprising of value added products.
type: integer
children:
description: The ages of the children allocated to this product.
type: array
items:
type: integer
minimum: 0
maximum: 17
deal:
title: Deal
description: This specifies the deal tagging for the product.
type:
- object
- 'null'
properties:
discount_percentage:
description: Discount percentage of the applied deal.
type: integer
minimum: 1
public_price:
description: Original price of this product, before applying any discounts.
type: number
format: double
multipleOf: 0.01
exclusiveMinimum: 0
tags:
description: The tags of all the applied deals.
type: array
items:
type: string
enum:
- black_friday
- limited_time_deal
- logged_in_deal
- mobile_rate
- seasonal_deal
inventory:
title: InventoryOutput
type: object
properties:
third_party:
type: boolean
description: Boolean value is "true" if the product is facilitated by a Booking.com partner company and "false" otherwise.
type:
description: Type of inventory - either net or sell rates.
type: string
enum:
- net
- sell
number_available_at_this_price:
description: Number of rooms available at this price.
type: integer
minimum: 1
nullable: true
number_of_adults:
description: The number of adults allocated to this product.
type: integer
minimum: 1
policies:
title: AccommodationsProductPolicies
description: The policies for this product.
type: object
properties:
cancellation:
title: AccommodationsProductCancellationPolicy
description: The cancellation policy for this product.
type: object
properties:
free_cancellation_until:
description: Until when the order for this product can be cancelled for free.
type:
- string
- 'null'
format: date-time
type:
description: 'The cancellation policy applicable to this product: "free_cancellation" allows a period for free cancellation, "non_refundable" means immediate loss of total amount, "special_conditions" means partly refundable.'
type: string
enum:
- free_cancellation
- non_refundable
- special_conditions
meal_plan:
title: AccommodationsProductMealPlanPolicy
description: The meal plan policy for this product.
type: object
properties:
meals:
description: The meals included in the meal plan.
type: array
items:
type: string
enum:
- breakfast
- dinner
- lunch
plan:
description: The meal plan included in this product.
type: string
enum:
- all_inclusive
- breakfast_included
- full_board
- half_board
- no_plan
payment:
title: AccommodationsProductPaymentPolicyNew
description: Payment terms and conditions for this product.
type: object
properties:
prepayment_required:
description: Whether prepayment is required for this product.
type: boolean
timings:
description: The payment timings supported by this product.
type: array
items:
type: string
enum:
- pay_at_the_property
- pay_online_later
- pay_online_now
price:
title: AccommodationsProductPrice
description: The price components of this product. 'base' and 'extra_charges' are returned only when explicitly requested (via 'extras=extra_charges').
type: object
properties:
base:
description: The base price. It does not include any extra charges.
type: number
format: double
multipleOf: 0.01
exclusiveMinimum: 0
book:
description: The display price that must be shown to the traveller under local booker protection laws. This price
# --- truncated at 32 KB (272 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/booking-holdings/refs/heads/main/openapi/booking-holdings-accommodations-api-openapi.yml