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

Booking.com 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
Production environment
https://demandapi.booking.com/3.1/
Sandbox environment
https://demandapi-sandbox.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.

bookerobject(Booker)required

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"
guestsobject(AccommodationsGuests)required

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://demandapi.booking.com/3.1/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(AccommodationsAvailabilityDataOutput)
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" } }

Get the availability of multiple properties

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
bookerobject(Booker)required

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(AccommodationsBulkAvailabilityFiltersInput)

The filters to apply in this availability request.

guestsobject(AccommodationsGuests)required

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://demandapi.booking.com/3.1/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(AccommodationsBulkAvailabilityDataOutput,)
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://demandapi.booking.com/3.1/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(AccommodationsChainsOutput)
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://demandapi.booking.com/3.1/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(ConstantsDataOutput)
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"

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://demandapi.booking.com/3.1/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(AccommodationsDetailsDataOutput)
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

filtersobject

parameter basis which filtering needs to be done. Only one of (countries or cities) must be provided.

curl -i -X POST \
  https://demandapi.booking.com/3.1/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",
    "filters": {
      "countries": [
        "nl",
        "es",
        "in"
      ]
    }
  }'
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(AccommodationDetailsChangesDataOutput)
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(AccommodationsReviewer)
rowsintegermultiple of 10[ 10 .. 100 ]

The maximum number of results to return.

Default 100
scoreobject(AccommodationsReviewScoreInput)
curl -i -X POST \
  https://demandapi.booking.com/3.1/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(AccommodationsReviewsDataOutput)
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(AccommodationsReviewer)
curl -i -X POST \
  https://demandapi.booking.com/3.1/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(AccommodationsReviewsScoresOutput)
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
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"

bookerobject(Booker)required

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"
brandsArray of integers
cancellation_typestring

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.

Enum"free_cancellation""non_refundable"
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.

cityinteger

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

coordinatesobject(AccommodationsSearchCoordinatesOutput)

Limit the result list to the specified coordinates.

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"

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"

districtinteger>= 1

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

dormitoriesstring

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.

Default "include"
Enum"include""exclude""only"
extrasArray of strings

Input parameter to request for additional information about the products.

Items Enum"extra_charges""products"
guestsobject(AccommodationsGuests)required

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.

landmarkinteger>= 1

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

meal_planstring

Filter the result based on the selected meal plan. Example: When specified breakfast_included, it will show the product with free breakfast.

Enum"all_inclusive""breakfast_included""full_board""half_board"
pagestring

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

paymentobject

The payment filter for the request

priceobject

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

ratingobject

The rating filter for the request

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.

room_facilitiesArray of integers
rowsintegermultiple of 10[ 10 .. 100 ]

The maximum number of results to return.

Default 100
sortobject

The sorting parameters for the response

travel_proudboolean

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.

curl -i -X POST \
  https://demandapi.booking.com/3.1/accommodations/search \
  -H 'Authorization: Bearer <YOUR_string_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Affiliate-Id: 0' \
  -d '{
    "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
    }
  }'
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(AccommodationsSearchDataOutput)
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": "..." }

cars

Endpoints and sections specific to car rentals.

Operations

common/locations

These are the endpoints you can use to retrieve the identifiers of a wide range of geographical locations: airports, countries, cities, regions, etc. Use them to construct your requests.

Operations

common/payments

Generic endpoints related to payments and finance: currencies, payment types, etc.

Operations

common

Operations

orders

Operations