openapi: 3.1.0
info:
title: Booking.com Demand API
version: '3.1'
summary: >
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.
[Check the try out guide!](/demand/docs/getting-started/try-out-the-api)
x-last-validated: '2026-06-02'
x-generated-from: documentation
servers:
- url: https://demandapi.booking.com/3.1
description: Production environment
- url: https://demandapi-sandbox.booking.com/3.1
description: Sandbox environment
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: string
parameters:
AffiliateIdHeader:
in: header
name: X-Affiliate-Id
schema:
type: integer
required: true
description: Include here your Affiliate identifier number
security:
- BearerAuth: []
tags:
- name: Accommodations
x-displayName: Accommodation
description: >-
This API collection is specific for the stay part of the connected trip.
</br></br>Use these endpoints to search for stays such as hotels and
apartments, check availability, retrieve reviews, and get detailed
property information.
- name: Cars
x-displayName: Car rentals
description: >-
This API collection is specific to the car rentals part of the connected
trip.</br></br> Use these endpoints to search for car rentals, check car
details and look for depots and suppliers.
- name: Common/locations
x-displayName: Locations
description: >-
Provides identifiers for a wide range of geographical locations, including
airports, countries, cities, and regions. </br></br>Use these identifiers
to construct your requests. </br></br>Note: These identifiers are
available across all travel services and you can use them for both
accommodotation and car rentals requests.
- name: Common/payments
x-displayName: Payments
description: >-
Provides generic payment-related endpoints, including supported currencies
and payment types.
- name: Common/languages
x-displayName: Languages
description: Provides a list of supported language codes for use in API requests.
- name: Orders
x-displayName: Orders
description: >-
Enables management of booking orders within the Demand API. </br></br>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.
- name: Messages
x-displayName: Messages
description: >-
Provides endpoints for two-way post-booking communication between guests
and properties. </br></br>Use these endpoints to send and retrieve
messages, exchange images, and check conversation details.
- name: Conversations
x-displayName: Conversations
description: >-
Provides endpoints to retrieve and manage messaging conversations.
</br></br>Use these endpoints to list conversations, fetch conversation
details, and track updates.
- name: Attachments
x-displayName: Attachments
description: >-
Provides endpoints for handling message attachments. </br></br>Use these
endpoints to upload and download images shared within conversations.
x-tagGroups:
- name: Travel services
tags:
- Accommodations
- Cars
- name: Common
tags:
- Common/locations
- Common/payments
- Common/languages
- name: Orders
tags:
- Orders
- name: Messaging
tags:
- Messages
- Conversations
- Attachments
paths:
/accommodations/search:
post:
summary: Booking.com Search Accommodation
description: >-
This endpoint returns, by default, the cheapest available product for
each accommodation that matches the specified search criteria.
<br/><br/>When you apply location filters using parameters such as
country or region id, the results are sorted by Booking.com popularity
(top_picks) instead of price.<br/>In this case, accommodations are
ranked in descending order of popularity, meaning higher-ranked listings
will appear earlier in the response.
operationId: accommodationsSearch
parameters:
- in: header
name: X-Affiliate-Id
schema:
type: integer
required: true
description: Include here your Affiliate identifier number
tags:
- Accommodations
requestBody:
content:
application/json:
schema:
title: AccommodationsSearchInput
type: object
properties:
24_hour_reception:
description: >-
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.
type: boolean
accommodation_facilities:
type: array
items:
description: >-
A signed integer number that uniquely identifies an
accommodation property facility. Examples of facilities
are: Parking, Restaurant, Room service etc. The full list
can be obtained by calling <a
href="/demand/docs/open-api/demand-api/accommodations/accommodations/constants"
target="_blank">accommodations/constants</a>.
type: integer
minimum: 1
accommodation_types:
type: array
items:
description: >-
A signed integer number that uniquely identifies an
accommodation property type. Examples of accommodation
types are: Apartment, Hostel, Hotel etc. The full list can
be obtained by calling <a
href="/demand/docs/open-api/demand-api/accommodations/accommodations/constants"
target="_blank">accommodations/constants</a>.
type: integer
minimum: 1
accommodations:
type: array
items:
description: >-
A signed integer number that uniquely identifies an
accommodation property. The full list can be obtained by
calling
[accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details).
type: integer
minimum: 1
maxItems: 100
airport:
description: >-
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 <a
href="/demand/docs/open-api/demand-api/commonlocations/common/locations/airports"
target="_blank">common/locations/airports</a>.
type: string
pattern: ^[A-Z]{3}$
example: AMS
booker:
title: Booker
description: The booker's information.
type: object
properties:
country:
description: >-
The booker country for showing the best price for that
user and obeying laws regarding the display of taxes and
fees.
type: string
pattern: ^[a-z]{2}$
platform:
description: >-
The booker platform for showing the platform based deals
and prices.
type: string
enum:
- android
- desktop
- ios
- mobile
- tablet
state:
description: >-
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.
type: string
pattern: ^[a-z]{2}$
travel_purpose:
description: The travel purpose of the booker.
type: string
enum:
- business
- leisure
user_groups:
description: The user groups that the booker is a member of.
type: array
items:
type: string
enum:
- authenticated
required:
- country
- platform
brands:
type: array
items:
description: >-
A signed integer number that uniquely identifies an
accommodation brand. Examples of brands are: Radisson Blu,
WestCord Hotels, Westin etc. The full list can be obtained
by calling <a
href="/demand/docs/open-api/demand-api/accommodations/accommodations/chains"
target="_blank">/accommodations/chains</a>.
type: integer
minimum: 1
cancellation_type:
description: >-
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.
type: string
enum:
- free_cancellation
- non_refundable
checkin:
description: >-
The checkin date. Must be within 500 days in the future and
in the format yyyy-mm-dd.
type: string
format: date
checkout:
description: >-
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.
type: string
format: date
city:
description: >-
A signed integer number that uniquely identifies a city. The
full list can be obtained by calling <a
href="/demand/docs/open-api/demand-api/commonlocations/common/locations/cities"
target="_blank">common/locations/cities</a>.
type: integer
coordinates:
title: AccommodationsSearchCoordinatesOutput
description: Limit the result list to the specified coordinates.
type: object
properties:
latitude:
description: >-
Specify a latitude (as well as a longitude and radius)
to do searches around a specific location.
type: number
format: double
longitude:
description: >-
Specify a longitude (as well as a latitude and radius)
to do searches around a specific location.
type: number
format: double
radius:
description: >-
The radius is km to search around the specified latitude
and longitude.
type: number
format: double
country:
description: >-
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 <a
href="/demand/docs/open-api/demand-api/commonlocations/common/locations/countries"
target="_blank">common/locations/countries</a>.
type: string
pattern: ^[a-z]{2}$
example: nl
currency:
description: >-
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 <a
href="/demand/docs/open-api/demand-api/commonpayments/common/payments/currencies"
target="_blank">common/payments/currencies</a>.
type: string
pattern: ^[A-Z]{3}$
example: EUR
district:
description: >-
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 <a
href="/demand/docs/open-api/demand-api/commonlocations/common/locations/districts"
target="_blank">common/locations/districts</a>.
type: integer
minimum: 1
dormitories:
description: >-
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.
type: string
default: include
enum:
- include
- exclude
- only
extras:
description: >-
Input parameter to request for additional information about
the products.
type: array
items:
type: string
enum:
- extra_charges
- products
guests:
title: AccommodationsGuests
description: The guest details for the request.
type: object
properties:
allocation:
description: The exact allocation of guests to rooms.
type: array
items:
properties:
children:
description: The children ages for this room.
type: array
items:
type: integer
minimum: 0
maximum: 17
number_of_adults:
description: The number of adults for this room.
type: integer
minimum: 1
required:
- number_of_adults
children:
description: Array with the children ages.
type: array
items:
type: integer
minimum: 0
maximum: 17
number_of_adults:
description: The number of adults for the search.
type: integer
minimum: 1
number_of_rooms:
description: The number of rooms needed.
type: integer
minimum: 1
required:
- number_of_adults
- number_of_rooms
landmark:
description: >-
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 <a
href="/demand/docs/open-api/demand-api/commonlocations/common/locations/landmarks"
target="_blank">common/locations/landmarks</a>.
type: integer
minimum: 1
meal_plan:
description: >-
Filter the result based on the selected meal plan. Example:
When specified breakfast_included, it will show the product
with free breakfast.
type: string
enum:
- all_inclusive
- breakfast_included
- full_board
- half_board
page:
description: >-
Pagination token used to retrieve the next page of results.
Obtained from `next_page`.
type: string
payment:
description: The payment filter for the request
type: object
properties:
credit_card_required:
description: Filter to show accommodations which require credit card
type: boolean
timing:
description: >-
This parameter specifies that the results should only
return accommodation and blocks that contain the
specified payment timings.
type: string
enum:
- pay_at_the_property
- pay_online
price:
description: >-
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
type: object
properties:
maximum:
description: >-
Set the maximum price per night, in the specified
currency, or omit to indicate no upper limit.
type: integer
minimum:
description: >-
Set the minimum price per night, in the specified
currency, or omit to indicate no lower limit.
type: integer
rating:
description: The rating filter for the request
type: object
properties:
minimum_review_score:
description: >-
Show only hotels with review_score >= that. Review score
should be in the range 1 to 10.
type: integer
minimum: 0
maximum: 10
stars:
description: >-
Limit to accommodations with the given number(s) of
stars. Stars should be in the range of 1 to 5.
type: array
items:
type: number
minimum: 1
maximum: 5
region:
description: >-
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 <a
href="/demand/docs/open-api/demand-api/commonlocations/common/locations/regions"
target="_blank">common/locations/regions</a>.
type: integer
minimum: 1
room_facilities:
type: array
items:
description: >-
A signed integer number that uniquely identifies an
accommodation property room facility. Examples of
facilities are: Coffee/Tea maker, TV, Airconditioning,
etc. The full list can be obtained by calling <a
href="/demand/docs/open-api/demand-api/accommodations/accommodations/constants"
target="_blank">accommodations/constants</a>.
type: integer
minimum: 1
rows:
description: The maximum number of results to return.
type: integer
multipleOf: 10
minimum: 10
maximum: 100
default: 100
sort:
description: The sorting parameters for the response
type: object
properties:
by:
description: >-
The way to sort your results. NOTE: When ordering by
distance please make sure to specify the latitude and
longitude!
type: string
enum:
- distance
- price
- review_score
- stars
direction:
description: >-
The direction you wish for your sort.by parameter to be
sorted in
type: string
enum:
- ascending
- descending
travel_proud:
description: >-
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.
type: boolean
required:
- booker
- checkin
- checkout
- guests
example:
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
responses:
'200':
description: Successful response.
content:
application/json:
schema:
title: AccommodationsSearchOutput
type: object
properties:
request_id:
description: >-
Uniquely identifies the request. Please provide this
identifier when contacting support.
type: string
data:
type: array
items:
title: AccommodationsSearchDataOutput
description: ''
type: object
properties:
id:
description: >-
A signed integer number that uniquely identifies an
accommodation property. The full list can be
obtained by calling
[accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details).
type: integer
minimum: 1
commission:
title: AccommodationsCommission
description: >-
Commission details for the partner for a given
accommodation
type: object
properties:
amount:
description: The actual commission amount for the partner.
type: number
format: double
minimum: 0
percentage:
description: >-
Percentage of the fee that will be received as
commission.
type: number
format: double
minimum: 0
currency:
description: >-
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
<a
href="/demand/docs/open-api/demand-api/commonpayments/common/payments/currencies"
target="_blank">common/payments/currencies</a>.
type: string
pattern: ^[A-Z]{3}$
example: EUR
deep_link_url:
description: >-
A mobile app URL that directs the user to a specific
page or content within the Booking.com app. The link
can only be used on a device with the Booking.com
app installed. It typically includes an Affiliate ID
(AID) to attribute bookings to the affiliate partner
when users are redirected
type: string
format: url
price:
title: AccommodationsSearchProductPrice
description: >-
The price components of this product or selection of
products. 'base' and 'extra_charges' are returned
only when explicitly requested (via
'extras=extra_charges').
type: object
properties:
base:
description: >-
The base price. It does not include any extra
charges.
type: number
format: double
multipleOf: 0.01
exclusiveMinimum: 0
book:
description: >-
The display price that must be shown to the
traveller under local booker protection laws.
This price includes the base accommodation cost
and all charges that are legally required to be
part of the displayed price. Equivalent to base
+ included charges.
type: number
format: double
multipleOf: 0.01
exclusiveMinimum: 0
extra_charges:
title: AccommodationsExtraCharges
description: The charge breakdown. Includes taxes and fees.
type: object
properties:
excluded:
description: Charges not included in 'book'.
type: number
format: double
minimum: 0
included:
description: Charges included in 'book'.
type: number
format: double
minimum: 0
total:
description: The total price. Includes all extra charges.
type: number
format: double
multipleOf: 0.01
exclusiveMinimum: 0
products:
type: array
items:
title: AccommodationsSearchProductOutput
description: >-
Details product information. It requires
`{"extras":["products"]}`.
type: object
properties:
id:
description: Unique ID of the product.
type: string
bundle:
description: >-
The bundle ID of the product comprising of
value added products.
type: integer
children:
description: >-
The ages of the children allocated to this
product.
type: array
items:
type: integer
minimum: 0
maximum: 17
deal:
title: Deal
description: >-
This specifies the deal tagging for the
product.
type:
- object
- 'null'
properties:
discount_percentage:
description: Discount percentage of the applied deal.
type: integer
minimum: 1
public_price:
description: >-
Original price of this product, before
applying any discounts.
type: number
format: double
multipleOf: 0.01
# --- truncated at 32 KB (726 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/booking-holdings/refs/heads/main/openapi/booking-com-demand-api.yaml