Search for available properties
→ Use the /accommodations/search endpoint to retrieve the list of accommodations that have at least one available product that matches the search criteria for a traveller's stay.
The request defines the search criteria to be used.
The response returns:
- The
id
of every accommodation that has at least one available product (or product combination) that matches the search criteria. - For each accommodation, the price of the product(s) that Booking.com recommends as the best match for the search criteria.
- In case the search criteria is for accommodations located in a specific
country
orregion
, the retrieved results are sorted by default based on "popularity" (also known as "Top picks"). - However, you can still optionally use other "Sort.by" options, to get results based on price, distance, etc, instead.
- The
Create the search request body
Travellers' search requirements can vary enormously, from the simple and precise to the vague and complex.
The /accommodations/search request schema provides an extensive range of input options. This allows you to construct search requests that can:
- Cover the whole spectrum of travellers' requirements as efficiently as possible.
- Find and return the optimum set of matching results for the traveller, so that they can find their ideal accommodation easily and quickly. This in turn maximises the chances of them converting the search to a booking.
Mandatory fields
The request body must contain the following fields:
- One (and only one) destination field.
- The basic details about the guest(s):
checkin
andcheckout
: their arrival and departure datesguests.number_of_adults:
the number of adults who will be stayingguests.number_of_rooms
: the number of rooms they need
- The basic details about the booker:
booker.platform
: the platform from which the request is being made. This ensures that any platform-based prices and deals can be returned correctly.booker.country
: the country from which the request is being made. This is required to ensure that the response complies with relevant laws on the display of taxes and fees.
See Example 1. All other fields are optional.
Destination fields
You must specify one (and only one) of the following fields to define the geographic target of the search request.
→ Use the /common/locations endpoints to get the id
you need to add in the desired destination field.
country
,region
: Note that if you use one of these fields, the returned results will be by default sorted by Popularity ranking ("Top picks") in descending order.city
,district
airport
orlandmark
coordinates
- An object defining thelatitude
andlongitude
of the centre of the search, and theradius
(in km) from that point defining the limit of the search.- You can get the coordinates of a
landmark
by using locations/landmarks, or of an accommodation by using /accommodations/details. - You can also use coordinates sourced in any other way.
- You can get the coordinates of a
accommodations
- A list of accommodationid
s. This could be:- A list built from the response to a previous search request.
- Or a list created for a specific purpose, for example: a promotion on your search page for a specific set of hotels near a particular beach.
See Example 2.
Guest details and room allocation
If any children will be staying, define the age of each child in the guests.children
field. For example, [3,3,8,12]
specifies four children, two aged 3, one aged 8 and one aged 12.
If you want specific combinations of guests to share individual rooms, use the guests.allocation
field.
- Create an array of objects under
guests.allocation
, one object for each room. - In each object:
- In
children
, add the age of each child who should occupy the room. Omit the field if no children are staying in this room. - In
number_of_adults
, add the number of adults who should occupy the room. Each room must contain at least one adult.
- In
Make sure that:
- The total number of objects matches the number specified in
guests.number_of_rooms
. - The total number of children allocated to rooms, and their ages, matches the information specified in
guests.children
. - The total number of adults allocated to rooms matches the number specified in
guests.number_of_adults
.
For example:
"guests": { "allocation": [{ "children": [13, 15], "number_of_adults": 1 }, { "children": [2, 3], "number_of_adults": 2 }, { "number_of_adults": 2 } ], "number_of_rooms": 3, "number_of_adults": 5, "children": [2, 3, 13, 15] }
Filter criteria
The following tables summarise the available filters, some of which work on the accommodation level, and some on the product level.
For specific information about each filter, see the request schema.
Accommodation-level filters
Field | Description |
---|---|
24_hour_reception | Only return accommodation that has 24-hour reception cover. |
accommodation_facilities | Only return accommodation that has a specific set of facilities. For example, a restaurant, sea view and tennis court. |
accommodation_types | Only return specific types of accommodation. For example, only return hotels, apartments and boats. |
brands | Only return accommodation that belongs to a particular corporate brand. |
dormitories | Include or exclude dormitory accommodation. |
rating.minimum_review_score | Only return accommodation that has a review score of at least n |
rating.stars | Only return accommodation that has a specific number of stars. |
travel_proud | Only return accommodation that is a member of the Booking.com Travel Proud programme. |
payment.timing | You can restrict results to only include properties that support pay at the property (pay_at_the_property ) or online payments (pay_online ). |
Product-level filters
Field | Description |
---|---|
room_facilities | Only return products with rooms that have a specific set of facilities. For example, air conditioning and a balcony. |
payment | Include or exclude products that require use of a credit card. |
price | Only return products in a specific price range. |
cancellation_type | Only return products that have a specific cancellation policy. |
meal_plan | Only return products that offer specific meal plans. For example, breakfast included or half-board. |
Extra information
By default, the response contains only basic information about matching accommodation and price. You can use the extras
field to return additional information about extra_charges
and products
, as shown in the following examples.
Example 1: Basic response (no extras
requested)
Each result in the list includes the following information:
- The accommodation's unique identifier (
id
). - the total
price
and currency of the product(s) that Booking.com recommends as the best match for the search criteria, - the
url
(anddeep_link_url
for mobile apps)
{ "id": 3882311, "currency": "GBP", "deep_link_url": "booking://hotel/3882311?affiliate_id=956509&checkin=2023-05-10&checkout=2023-05-12&mcid=10", "price": { "book": 180.34, "total": 180.34 }, "url": "https://www.booking.com/hotel/nl/demand-api-test-1.html?aid=956509&checkin=2023-05-10&checkout=2023-05-12&no_rooms=1&group_adults=2&selected_currency=GBP&mcid=10" }
Example 2: With extra_charges
When extra_charges
are returned (without products
), each result also includes a summary breakdown of the charges applied to the price of the recommended product (or product combination).
See the schema description of the price object for more details.
{ "id": 3882311, "currency": "GBP", "deep_link_url": "booking://hotel/3882311?affiliate_id=956509&checkin=2023-05-10&checkout=2023-05-12&mcid=10", "price": { "base": 176.81, "book": 180.34, "extra_charges": { "excluded": 0.00, "included": 3.54 }, "total": 180.34 }, "url": "https://www.booking.com/hotel/nl/demand-api-test-1.html?aid=956509&checkin=2023-05-10&checkout=2023-05-12&no_rooms=1&group_adults=2&selected_currency=GBP&mcid=10" }
Example 3: With products
When products
are returned (without extra_charges
), each result also includes the following information about each included product:
- The type of room that is included.
- The number of adults and children (shown by their ages) allocated to the room.
- The applicable cancellation, meal and payment policies.
- Any deals that are applied.
- The price.
Refer to the schema description of the products.policies object for more details.
{ "id": 3882311, "currency": "GBP", "deep_link_url": "booking://hotel/3882311?affiliate_id=956509&checkin=2023-05-10&checkout=2023-05-12&mcid=10", "price": { "book": 180.34, "total": 180.34 }, "products": [{ "id": "388231102_367857842_0_2_0", "children": [], "deal": null, "number_of_adults": 2, "policies": { "cancellation": { "free_cancellation_until": "2023-05-02T21:59:59+00:00", "type": "free_cancellation" }, "meal_plan": { "meals": [], "plan": "no_plan" }, "payment": { "types": [ "pay_now", "pay_later" ] } }, "price": { "book": 180.34, "total": 180.34 }, "room": 388231102 }], "url": "https://www.booking.com/hotel/nl/demand-api-test-1.html?aid=956509&checkin=2023-05-10&checkout=2023-05-12&no_rooms=1&group_adults=2&selected_currency=GBP&mcid=10" }
Example 4: With both products
and extra_charges
When products
and extra_charges
are returned, each result also includes a complete breakdown of every charge that has been applied to each product. The breakdown shows the id
of the charge type, how it is applied, and how it is calculated.
See the schema description of the products.price object for more details.
{ "id": 3882311, "currency": "GBP", "deep_link_url": "booking://hotel/3882311?affiliate_id=956509&checkin=2023-05-10&checkout=2023-05-12&mcid=10", "price": { "base": 176.81, "book": 180.34, "extra_charges": { "excluded": 0.00, "included": 3.54 }, "total": 180.34 }, "products": [{ "id": "388231102_367857842_0_2_0", "children": [], "deal": null, "number_of_adults": 2, "policies": { "cancellation": { "free_cancellation_until": "2023-05-02T21:59:59+00:00", "type": "free_cancellation" }, "meal_plan": { "meals": [], "plan": "no_plan" }, "payment": { "types": [ "pay_now", "pay_later" ] } }, "price": { "base": 176.81, "book": 180.34, "extra_charges": { "conditional": [], "excluded": [], "included": [{ "charge": 1, "mode": "per_person_per_night", "percentage": null, "total_amount": 3.54, "unit_amount": 0.88 }] }, "total": 180.34 }, "room": 388231102 }], "url": "https://www.booking.com/hotel/nl/demand-api-test-1.html?aid=956509&checkin=2023-05-10&checkout=2023-05-12&no_rooms=1&group_adults=2&selected_currency=GBP&mcid=10" }
Search request examples
Example 1
A couple looking for an overnight stay in Amsterdam. This is a very basic request that uses only the mandatory fields.
Use city
as the destination. You can obtain the id
for Amsterdam from /common/locations/cities
.
{ "city": -2140479, "booker": { "platform": "desktop", "country": "gb" }, "checkin": "2023-03-09", "checkout": "2023-03-10", "guests": { "number_of_rooms": 1, "number_of_adults": 2 } }
Example 2
A business traveller looking for an overnight stay in Amsterdam, who wants a hotel within a short walk of the Amsterdam Central Station.
- Use
coordinates
rather thancity
as the destination. To obtain thelatitude
andlongitude
of the Amsterdam Central Station, call/common/locations/landmarks
, using Amsterdam'sid
(-2140479
) as an input. - Define the
radius
for the search as1
km. - Add a filter for
accommodation_types
to include only hotels (204
). You can get this id from/accommodations/constants
. - Sort the results by
distance
, so that hotels closest to the station are highest in the list.
{ "coordinates": { "latitude": 52.378281, "longitude": 4.900070, "radius": 1 }, "accommodation_types": [204], "booker": { "platform": "desktop", "country": "gb" }, "currency": "GBP", "checkin": "2023-03-09", "checkout": "2023-03-10", "guests": { "number_of_rooms": 1, "number_of_adults": 1 }, "sort": { "by": "distance", "direction": "descending" } }
Example 3
A family group are in the early stages of planning a holiday somewhere in Spain, with a beachfront location. They are looking for a week or so in mid-late August in a hotel, resort or villa, with an 8+ review score. They will need 3 rooms, for:
- 2 parents with 2 young children, aged 2, 3.
- A single parent with two teenage children, aged 13 and 15
- 2 grandparents
The parents want to play tennis. The grandparents want a room with air-conditioning and a shower.
To meet these requirements in the search:
Use filters for:
accommodation_facilities
, to include only accommodations that list tennis court (9
) and beach front (146) as available facilities.accommodation_types
, to include only hotels (204
), resorts (206) and villas (213).rating.minimum_review_score
, to include only accommodations with an 8+ review score.room_facilities
, to include only products that include rooms with air-conditioning (11
) and a shower (4
).You can obtain the necessary
id
s by calling/accommodations/constants
.
Use
guests.children
to specify the age of each child in the group.Use
guests.allocation
to specify the desired occupancy - adults and children - for each requested room.
Also, because the recommended product(s) will include multiple rooms, use the extras
field to include details of the product(s) in the response.
{ "country": "es", "accommodation_facilities": [9, 146], "accommodation_types": [204, 206, 213], "booker": { "platform": "desktop", "country": "nl" }, "currency": "EUR", "checkin": "2023-08-08", "checkout": "2023-08-16", "guests": { "allocation": [{ "children": [13, 15], "number_of_adults": 1 }, { "children": [2, 3], "number_of_adults": 2 }, { "number_of_adults": 2 } ], "number_of_rooms": 3, "number_of_adults": 5, "children": [2, 3, 13, 15] }, "rating": { "minimum_review_score": 8 }, "room_facilities": [4, 11] }
Search response
Our search results are also a recommendation system. They show all the accommodations that match your search criteria based on different variables.
Although the search system takes prices as the main variable for the results ranking, there is a particular case in which results are retrieved based on "popularity" ("Our top picks").
- If you specify the
country
orregion
in the search request, the results will be sorted by popularity ("Top picks") (in descending order). - Hence, the most "popular" accommodations for the selected location will appear high up on the results page by default.
If you decide to use the "Sort.by" with any of the given options, like price
or distance
, then the search results will retrieve accommodations based on that sorting criteria instead.