Unfortunately, this feature is not supported on mobile devices. For the best experience, please use a computer.

Demand API (3.1)

Our Demand API offers a wide range of functionalities for affiliate partners to be able to retrieve data from Booking.com inventory.

- Based on basic REST principles, our endpoints return JSON data directly from our system.
- You can consume them directly through HTTPS calls, using the POST method.

Download OpenAPI description
Languages
Servers
Mock server
https://developers.booking.com/_mock/demand/docs/open-api/demand-api/
https://demandapi-sandbox.booking.com/3.1/
https://demandapi.booking.com/3.1/

accommodations

Endpoints and sections specific to the accommodations travel vertical: hotels, apartments, etc.

Operations

Get a property's availability

Request

This endpoint returns detailed product availability, price and charges of the accommodation matching a given search criteria. By default, only product availability and price is returned. To receive extended information use the extras parameter. Is is mandatory to pass the input parameters: accommodation, booker, checkin, checkout and guest.

Headers
X-Affiliate-Idintegerrequired

Affiliate identifier

Bodyapplication/json
accommodationinteger>= 1required

A signed integer number that uniquely identifies an accommodation property. The full list can be obtained by calling accommodations/details.

bookerobjectrequired

The booker's information.

booker.countrystring^[a-z]{2}$required

The booker country for showing the best price for that user and obeying laws regarding the display of taxes and fees.

booker.platformstringrequired

The booker platform for showing the platform based deals and prices.

Enum"android""desktop""ios""mobile""tablet"
booker.statestring^[a-z]{2}$

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.

booker.travel_purposestring

The travel purpose of the booker.

Enum"business""leisure"
booker.user_groupsArray of strings

The user groups that the booker is a member of.

Items Value"authenticated"
checkinstring(date)required

The checkin date. Must be within 500 days in the future and in the format yyyy-mm-dd.

checkoutstring(date)required

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.

currencystring^[A-Z]{3}$

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 common/payments/currencies.

Example:

"EUR"

extrasArray of strings

Input parameter to request for additional information about this product.

Items Value"extra_charges"
guestsobjectrequired

The guest details for the request.

guests.allocationArray of objects

The exact allocation of guests to rooms.

guests.childrenArray of integers

Array with the children ages.

guests.number_of_adultsinteger>= 1required

The number of adults for the search.

guests.number_of_roomsinteger>= 1required

The number of rooms needed.

paymentobject

Payment input information to filter results.

productsArray of strings
curl -i -X POST \
  https://developers.booking.com/_mock/demand/docs/open-api/demand-api/accommodations/availability \
  -H 'Authorization: Bearer <YOUR_string_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Affiliate-Id: 0' \
  -d '{
    "accommodation": 10004,
    "booker": {
      "country": "nl",
      "platform": "desktop"
    },
    "checkin": "!START_DATE!",
    "checkout": "!END_DATE!",
    "extras": [
      "extra_charges"
    ],
    "guests": {
      "number_of_adults": 2,
      "number_of_rooms": 1
    }
  }'
Experience it firsthand in the API Explorer!

Responses

Successful response.

Bodyapplication/json
request_idstring

Uniquely identifies the request. Please provide this identifier when contacting support.

dataobject
Response
application/json
{ "request_id": "01fr9ez700exycb98w90w5r9sh", "data": { "id": 10004, "currency": "EUR", "deep_link_url": "booking://hotel/10004?affiliate_id=!AFFILIATE_ID!&checkin=!START_DATE!&checkout=!END_DATE!", "products": [], "recommendation": {}, "url": "https://www.booking.com/hotel/nl/toren.html?aid=!AFFILIATE_ID!&checkin=!START_DATE!&checkout=!END_DATE!&no_rooms=1&group_adults=2" } }

List properties' availabilities

Request

This endpoint returns detailed product availability, price and charges of a list of accommodations. By default, only product availability and price is returned. To receive extended information use the extras parameter. Is is mandatory to pass the input parameters: accommodations, booker, checkin, checkout and guests.

Headers
X-Affiliate-Idintegerrequired

Affiliate identifier

Bodyapplication/json
accommodationsArray of integers<= 50 itemsrequired
bookerobjectrequired

The booker's information.

booker.countrystring^[a-z]{2}$required

The booker country for showing the best price for that user and obeying laws regarding the display of taxes and fees.

booker.platformstringrequired

The booker platform for showing the platform based deals and prices.

Enum"android""desktop""ios""mobile""tablet"
booker.statestring^[a-z]{2}$

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.

booker.travel_purposestring

The travel purpose of the booker.

Enum"business""leisure"
booker.user_groupsArray of strings

The user groups that the booker is a member of.

Items Value"authenticated"
checkinstring(date)required

The checkin date. Must be within 500 days in the future and in the format yyyy-mm-dd.

checkoutstring(date)required

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.

currencystring^[A-Z]{3}$

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 common/payments/currencies.

Example:

"EUR"

extrasArray of strings

Input parameter to request for additional information about this product.

Items Value"extra_charges"
filtersobject

The filters to apply in this availability request.

guestsobjectrequired

The guest details for the request.

guests.allocationArray of objects

The exact allocation of guests to rooms.

guests.childrenArray of integers

Array with the children ages.

guests.number_of_adultsinteger>= 1required

The number of adults for the search.

guests.number_of_roomsinteger>= 1required

The number of rooms needed.

curl -i -X POST \
  https://developers.booking.com/_mock/demand/docs/open-api/demand-api/accommodations/bulk-availability \
  -H 'Authorization: Bearer <YOUR_string_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Affiliate-Id: 0' \
  -d '{
    "accommodations": [
      10004
    ],
    "booker": {
      "country": "nl",
      "platform": "desktop"
    },
    "checkin": "!START_DATE!",
    "checkout": "!END_DATE!",
    "extras": [
      "extra_charges"
    ],
    "filters": {
      "meal_plan": "breakfast_included",
      "cancellation_type": "free_cancellation"
    },
    "guests": {
      "number_of_adults": 2,
      "number_of_rooms": 1
    }
  }'
Experience it firsthand in the API Explorer!

Responses

Successful response.

Bodyapplication/json
request_idstring

Uniquely identifies the request. Please provide this identifier when contacting support.

dataArray of objects
Response
application/json
{ "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ {} ] }

List accommodation chains

Request

A chain-branded accommodation is one that is associated with a larger corporation group, and as such, operates under a recognized brand. The information returned can be used to filter accommodation searches based on particular chains or brands. An example of a chain is "Radisson Hotel Group". To get the full list call the endpoint passing an empty body. The codes returned are what is used as input and output for other endpoints.

Headers
X-Affiliate-Idintegerrequired

Affiliate identifier

curl -i -X POST \
  https://developers.booking.com/_mock/demand/docs/open-api/demand-api/accommodations/chains \
  -H 'Authorization: Bearer <YOUR_string_HERE>' \
  -H 'X-Affiliate-Id: 0'
Experience it firsthand in the API Explorer!

Responses

Successful response.

Bodyapplication/json
request_idstring

Uniquely identifies the request. Please provide this identifier when contacting support.

dataArray of objects
Response
application/json
{ "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ {}, "..." ] }

List accommodation constants

Request

This endpoint enumerates the internal codes and names, in the selected languages, for relevant accommodation specific types. These accommodation specific types include the list of facilities that may be available at a property like "Elevator" or "Swimmingpool Outdoor". For example, the following parameters will return the full list in English (US) and French: {"languages":"en-us","fr"}. To get the full list call the endpoint passing an empty body. The codes returned are what is used as input and output for other endpoints in the accommodations namespace.

Headers
X-Affiliate-Idintegerrequired

Affiliate identifier

Bodyapplication/json
constantsArray of strings

Allows to filter the results only for specific sections.

Items Enum"accommodation_facilities""accommodation_themes""accommodation_types""bed_types""charge_types""facility_types""review_scores""room_facilities""room_types"
languagesArray of strings
Default ["en-gb"]
Example:

["en-us"]

curl -i -X POST \
  https://developers.booking.com/_mock/demand/docs/open-api/demand-api/accommodations/constants \
  -H 'Authorization: Bearer <YOUR_string_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Affiliate-Id: 0' \
  -d '{
    "languages": [
      "en-gb",
      "zh-cn"
    ]
  }'
Experience it firsthand in the API Explorer!

Responses

Successful response.

Bodyapplication/json
request_idstring

Uniquely identifies the request. Please provide this identifier when contacting support.

dataobject
Response
application/json
{ "request_id": "01fr9ez700exycb98w90w5r9sh", "data": { "accommodation_facilities": [], "accommodation_themes": [], "accommodation_types": [], "bed_types": [], "charge_types": [], "facility_types": [], "review_scores": [], "room_facilities": [], "room_types": [] } }

List accommodation details

Request

This endpoint returns detailed information on all accommodation properties matching a given search criteria. By default, only basic information is returned. To receive extended information use the extras parameter. Is is mandatory to pass one of the input parameters: accommodations, airport, city, country or region.

Headers
X-Affiliate-Idintegerrequired

Affiliate identifier

Bodyapplication/json
accommodation_facilitiesArray of integers
accommodation_typesArray of integers
accommodationsArray of integers<= 100 items
airportstring^[A-Z]{3}$

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 common/locations/airports.

Example:

"AMS"

beta_featuresArray of strings

Input parameter to request the beta features to be used. It should be passed as a JSON array with one or more items.

Items Value"beta_accommodations_details_use_facilities_301"
brandsArray of integers
cityinteger

A signed integer number that uniquely identifies a city. The full list can be obtained by calling common/locations/cities.

countrystring^[a-z]{2}$

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 common/locations/countries.

Example:

"nl"

extrasArray of strings

Input parameter to request for additional information about the accommodation property. It should be passed as a JSON array with one or more items.

Items Enum"description""facilities""payment""photos""policies""rooms"
languagesArray of strings
Example:

["en-us"]

pagestring

Pagination token used to retrieve the next page of results. Obtained from next_page.

paymentobject

Payment input information to filter results.

regioninteger>= 1

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 common/locations/regions.

rowsintegermultiple of 10[ 10 .. 1000 ]

The maximum number of results to return.

Default 100
curl -i -X POST \
  https://developers.booking.com/_mock/demand/docs/open-api/demand-api/accommodations/details \
  -H 'Authorization: Bearer <YOUR_string_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Affiliate-Id: 0' \
  -d '{
    "accommodations": [
      10004
    ],
    "extras": [
      "description",
      "facilities",
      "payment",
      "photos",
      "policies",
      "rooms"
    ],
    "languages": [
      "en-gb",
      "zh-cn"
    ]
  }'
Experience it firsthand in the API Explorer!

Responses

Successful response.

Bodyapplication/json
request_idstring

Uniquely identifies the request. Please provide this identifier when contacting support.

dataArray of objects
next_pagestring or null

Indicates that more results are available. Use this pagination token to retrieve the next page of results (via parameter page).

Response
application/json
{ "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ {} ] }

List new and updated accommodation

Request

This endpoint returns all accommodations that have closed, opened or changed relevant content since the given timestamp up to a limit of around 5000 ids. It is recommended to cache accommodation information locally in order to speed up responses. Use this endpoint in combination with accommodations/details to maintain the local cache up-to-date. The number of accommodation ids returned may vary since some may be removed due to blacklisting, while all changes from the last second will be included even if already beyond the 5000 ids threshold. Multiple changes to the same accommodation are grouped by intervals of 30 minutes in order to reduce the number of records.

Headers
X-Affiliate-Idintegerrequired

Affiliate identifier

Bodyapplication/json
last_changestring(date-time)required

The timestamp in ISO-8601 format from which changes to accommodations are returned (inclusive). Only UTC time zone is supported. We support changes for last 24 hours. Format: YYYY-MM-DDTHH:mm:ss+00:00

curl -i -X POST \
  https://developers.booking.com/_mock/demand/docs/open-api/demand-api/accommodations/details/changes \
  -H 'Authorization: Bearer <YOUR_string_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Affiliate-Id: 0' \
  -d '{
    "last_change": "!START_DATE!T12:00:00+00:00"
  }'
Experience it firsthand in the API Explorer!

Responses

Successful response.

Bodyapplication/json
request_idstring

Uniquely identifies the request. Please provide this identifier when contacting support.

dataobject
Response
application/json
{ "request_id": "01fr9ez700exycb98w90w5r9sh", "data": { "changes": {}, "from": "!START_DATE!T12:00:00+00:00", "next": "!START_DATE!T12:24:42+00:00", "total_changes": 5125 } }

List accommodation reviews

Request

This endpoint returns reviews for the specified accommodations. The reviews returned can be filtered. This endpoint implements pagination of the results. By specifying rows parameter, you can limit reviews for each accommodation.

Headers
X-Affiliate-Idintegerrequired

Affiliate identifier

Bodyapplication/json
accommodationsArray of integers<= 100 itemsrequired
languagesArray of strings

Limits reviews to those written in this language.

Example:

["en-us"]

last_changestring(date)

Limits the reviews to those changed after the given date. Format: YYYY-MM-DD.

pagestring

Pagination token used to retrieve the next page of results. Obtained from next_page.

reviewerobject
rowsintegermultiple of 10[ 10 .. 100 ]

The maximum number of results to return.

Default 100
scoreobject
curl -i -X POST \
  https://developers.booking.com/_mock/demand/docs/open-api/demand-api/accommodations/reviews \
  -H 'Authorization: Bearer <YOUR_string_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Affiliate-Id: 0' \
  -d '{
    "accommodations": [
      10004
    ],
    "languages": [
      "en-gb"
    ]
  }'
Experience it firsthand in the API Explorer!

Responses

Successful response.

Bodyapplication/json
request_idstring

Uniquely identifies the request. Please provide this identifier when contacting support.

dataArray of objects
next_pagestring or null

Indicates that more results are available. Use this pagination token to retrieve the next page of results (via parameter page).

Response
application/json
{ "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ {} ], "next_page": "..." }

List accommodation review scores

Request

This endpoint returns score distribution and score breakdown for the specified accommodations. The scores information can be filtered by reviewer parameters and languages.

Headers
X-Affiliate-Idintegerrequired

Affiliate identifier

Bodyapplication/json
accommodationsArray of integers<= 100 itemsrequired
languagesArray of strings

Limits reviews to those written in this language.

Example:

["en-us"]

reviewerobject
curl -i -X POST \
  https://developers.booking.com/_mock/demand/docs/open-api/demand-api/accommodations/reviews/scores \
  -H 'Authorization: Bearer <YOUR_string_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Affiliate-Id: 0' \
  -d '{
    "accommodations": [
      10004
    ],
    "languages": [
      "en-gb"
    ]
  }'
Experience it firsthand in the API Explorer!

Responses

Successful response.

Bodyapplication/json
request_idstring

Uniquely identifies the request. Please provide this identifier when contacting support.

dataArray of objects
Response
application/json
{ "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ {} ] }

List available accommodation

Request

This endpoint returns the cheapest available product for each hotel matching the search criteria.

Headers
X-Affiliate-Idintegerrequired

Affiliate identifier

Bodyapplication/json
24_hour_receptionboolean

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.

accommodation_facilitiesArray of integers
accommodation_typesArray of integers