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

demand-api.json

demand-api.yaml

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

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

List 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

Affiliate identifier

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.1/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"
    ]
  }'

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

Share your feedback about this section

List 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

Affiliate identifier

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.1/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"
    ]
  }'

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

Share your feedback about this section

List 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 country codes returned are what is used as input and output for other endpoints. This endpoint implements pagination of the results.

Headers

X-Affiliate-Idintegerrequired

Affiliate identifier

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.1/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"
    ]
  }'

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

Share your feedback about this section

List districts

Request

This endpoint returns a list of districts with translations in the selected languages. The districts returned may be filtered by a location id. For example, you can get the list of districts in Amsterdam by passing: {"city":-2140479}. To get the full list call the endpoint passing an empty body. The district ids returned are what is used as input and output for other endpoints. This endpoint implements pagination of the results.

Headers

X-Affiliate-Idintegerrequired

Affiliate identifier

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.1/common/locations/districts \
  -H 'Authorization: Bearer <YOUR_string_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Affiliate-Id: 0' \
  -d '{
    "city": -2140479,
    "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(DistrictOutput)

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
}

Share your feedback about this section

List landmarks

Request

This endpoint returns a list of relevant geographical landmark codes and their names in the selected languages. The landmarks returned may be filtered by a location id. For example, you can get the list of landmarks that are associated with the city of Paris in France by passing: {"city":-1456928}. To get the full list call the endpoint passing an empty body. The landmark codes returned are what is used as input and output for other endpoints. This endpoint implements pagination of the results.

Headers

X-Affiliate-Idintegerrequired

Affiliate identifier

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.1/common/locations/landmarks \
  -H 'Authorization: Bearer <YOUR_string_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Affiliate-Id: 0' \
  -d '{
    "city": -2140479,
    "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(LandmarkOutput)

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

Share your feedback about this section

List regions

Request

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

Headers

X-Affiliate-Idintegerrequired

Affiliate identifier

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"

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.1/common/locations/regions \
  -H 'Authorization: Bearer <YOUR_string_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Affiliate-Id: 0' \
  -d '{
    "country": "nl",
    "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(RegionOutput)

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
}

Share your feedback about this section

common/payments

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

Operations

common

Operations

orders

Operations