Booking.com Demand API (3.2)

v3.2

Demand API version 3.2 introduces several improvements and breaking changes from version 3.1, including updates to accommodation booking flows, inclusion of Attractions in orders/details for post-booking reporting and other structural enhancements.

The API follows REST principles and returns data in JSON format.
You can access endpoints via HTTPS POST requests.

Authentication: Use your Affiliate ID and token credentials to use these endpoints.

Try it out!

Download OpenAPI description

demand-api.json

demand-api.yaml

Servers

Production environment – use for live integrations.

https://demandapi.booking.com/3.2/

Sandbox environment – use for testing and validation.

https://demandapi-sandbox.booking.com/3.2/

Accommodation

v3.2

This collection includes endpoints related to stays within the connected trip experience.

Use these endpoints to:

Search for hotels, apartments, and other accommodation types.
Check real-time availability and pricing.
Retrieve property details and guest reviews.

Operations

Car rentals

v3.2

This collection includes endpoints related to car rental services within the connected trip experience.

Use these endpoints to:

Search and retrieve car details.
Retrieve car specifications, depot locations, and supplier information.

Operations

Locations

v3.2

This collection provides standardised location identifiers for geographical entities such as airports, countries, cities, and regions.

Use the returned identifiers when constructing requests across all travel services API collections, including both accommodation and car rental endpoints.

Operations

Airports

Request

This endpoint returns a list of airport codes and their names in the selected languages. The airports returned may be filtered by a location id. For example, you can get the list of airports in The Netherlands by passing: {"country":"nl"}. To get the full list call the endpoint passing an empty body. The airport codes returned are what is used as input and output for other endpoints. This endpoint implements pagination of the results.

Headers

X-Affiliate-Idintegerrequired

Include here your Affiliate identifier number

Bodyapplication/json

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"

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"

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.

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.

languagesArray of strings

Default ["en-gb"]

Example: ["en-us"]

pagestring

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

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.2/common/locations/airports \
  -H 'Authorization: Bearer <YOUR_string_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Affiliate-Id: 0' \
  -d '{
    "country": "nl",
    "languages": [
      "en-gb",
      "zh-cn"
    ]
  }'

Responses

Successful response.

Bodyapplication/json

request_idstring

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

dataArray of objects(AirportOutput)

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": null
}

Cities

Request

This endpoint returns a list of city codes and their names in the selected languages. The cities returned may be filtered by a location id. For example, you can get the list of cities in The Netherlands by passing: {"country":"nl"}. To get the full list call the endpoint passing an empty body. The city codes returned are what is used as input and output for other endpoints. This endpoint implements pagination of the results.

Headers

X-Affiliate-Idintegerrequired

Include here your Affiliate identifier number

Bodyapplication/json

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"

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}$

Example: "nl"

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.

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.

languagesArray of strings

Default ["en-gb"]

Example: ["en-us"]

pagestring

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

regioninteger>= 1

rowsintegermultiple of 10[ 10 .. 1000 ]

The maximum number of results to return.

Default 100

curl -i -X POST \
  https://demandapi.booking.com/3.2/common/locations/cities \
  -H 'Authorization: Bearer <YOUR_string_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Affiliate-Id: 0' \
  -d '{
    "country": "nl",
    "languages": [
      "en-gb",
      "zh-cn"
    ]
  }'

Responses

Successful response.

Bodyapplication/json

request_idstring

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

dataArray of objects(CityOutput)

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": "..."
}

Countries

Request

This endpoint returns a list of country codes and their names in the selected languages. The countries returned may be filtered by a location id. For example, you can get the list of countries that are associated with the European Alps region by passing: {"region":1199}.

To get the full list call the endpoint passing an empty body. The returned country codes are used as input and output for other endpoints.

This endpoint implements pagination of the results.

Headers

X-Affiliate-Idintegerrequired

Include here your Affiliate identifier number

Bodyapplication/json

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"

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}$

Example: "nl"

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.

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.

languagesArray of strings

Default ["en-gb"]

Example: ["en-us"]

pagestring

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

regioninteger>= 1

rowsintegermultiple of 10[ 10 .. 1000 ]

The maximum number of results to return.

Default 100

curl -i -X POST \
  https://demandapi.booking.com/3.2/common/locations/countries \
  -H 'Authorization: Bearer <YOUR_string_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Affiliate-Id: 0' \
  -d '{
    "languages": [
      "en-gb",
      "zh-cn"
    ]
  }'

Responses

Successful response.

Bodyapplication/json

request_idstring

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

dataArray of objects(CountryOutput)

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": "..."
}

Payments

v3.2

Provides generic payment-related identifiers, including supported currency codes, payment cards, and relevant metadata for booking flows.

Use the returned identifiers when constructing requests across all travel services API collections, including both accommodation and car rental endpoints.

Operations

Languages

v3.2

Use this endpoint to retrieve a list of supported IETF language tag codes.

You can use these codes when constructing requests across all travel services API collections, including both accommodation and car rental endpoints.

Operations

Orders

v3.2

This API collection enables management of booking orders within the Demand API.
Use these endpoints to:

Preview and create new orders.
Check order details.
Cancel or modify existing orders. This collection is required to integrate booking and order management functionality.

Operations