Updated accommodations

Booking.com Demand API (3.1)

v3.1 Stable

The Booking.com Demand API enables Affiliate Partners to access Booking.com's travel inventory, including accommodations, car rentals, and flights.

Use Demand API to search, retrieve details, check availability, manage bookings and run reports using orders details.

RESTful API with JSON responses.
Make HTTPS POST requests to interact with endpoints.
Requires authentication using your Affiliate ID and token credentials.

Try it out!

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/

Accommodation

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.

Operations

Details

Request

This endpoint returns detailed information on all accommodation properties matching a given search criteria. By default, only basic information is returned.

It is mandatory to pass one of the input parameters: accommodations, airport, city, country or region.

To receive extended information use the extras parameter.

Headers

X-Affiliate-Idintegerrequired

Include here your Affiliate identifier number

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""bundles""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": [
      "bundles",
      "description",
      "facilities",
      "payment",
      "photos",
      "policies",
      "rooms"
    ],
    "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(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": [
    { … }
  ]
}

Updated accommodations

Request

Use this endpoint to track accommodations that have opened, closed, or had relevant content updates since a specific timestamp. Changes can include updates to general information, facilities, rooms, photos, payments, and more.
You can:
- Filter results by country or city.
- Use the "next" timestamp from the response to request further updates.

To keep your local accommodation cache up to date, use this endpoint in combination with accommodations/details

The maximum number of IDs returned is approximately 5000 per request.

Headers

X-Affiliate-Idintegerrequired

Include here your Affiliate identifier number

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

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

Accommodation reviews

Request

This endpoint provides access to reviews for specified accommodations, allowing you to retrieve traveller feedback associated with a particular property.

✅ The reviews returned can be filtered and sorted, with the option to limit the number of reviews per accommodation by specifying the rows parameter.

Please note that the ratings score is based on all traveller traffic across Booking.com, and may not necessarily reflect the experience of your own customers.

If you choose to display or use these ratings and reviews, you are responsible for ensuring that your travellers are properly informed about what these scores represent.

Headers

X-Affiliate-Idintegerrequired

Include here your Affiliate identifier number

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

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

Car rentals

This API collection is specific to the car rentals part of the connected trip.

Use these endpoints to search for car rentals, check car details and look for depots and suppliers.

Operations

Locations

Provides identifiers for a wide range of geographical locations, including airports, countries, cities, and regions.

Use these identifiers to construct your requests.

Note: These identifiers are available across all travel services and you can use them for both accommodotation and car rentals requests.

Operations

Payments

Provides generic payment-related endpoints, including supported currencies and payment types.

Operations

Languages

Provides a list of supported language codes for use in API requests.

Operations

Orders

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

Messages

Provides endpoints for two-way post-booking communication between guests and properties.

Use these endpoints to send and retrieve messages, exchange images, and check conversation details.

Operations

Conversations

Provides endpoints to retrieve and manage messaging conversations.

Use these endpoints to list conversations, fetch conversation details, and track updates.

Operations

Attachments

Provides endpoints for handling message attachments.

Use these endpoints to upload and download images shared within conversations.

Operations

Booking.com Demand API (3.1)

Accommodation

Details

RequestExpand all

Responses

Updated accommodations

RequestExpand all

Responses

Accommodation reviews

RequestExpand all

Responses

Car rentals

Locations

Payments

Languages

Orders

Messages

Conversations

Attachments

Request

Request

Request