Search for accommodation

Learn about the accommodation/search endpoint, the mandatory and optional fields you need to pass in each request to retrieve accommodations that match your travellers' preferences.

→ 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 rate and match for your search.

Create the search request body

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.

Example of search request for accommodations in UK and city -2612321.

"booker": {
"country": "gb",
"platform": "desktop"
},
"checkin": "2024-09-12",
"checkout": "2024-09-14",
"city": -2612321,
"extras": [
"extra_charges",
"products"
],
"guests": {
"number_of_adults": 4,
"number_of_rooms": 2
}

1. Define booker information

The request body must contain the basic details about the booker:

• booker.country: The two-letters country code from which the request is being made.

  • Get this code running the /common/locations/country endpoint.
  • Note it must always be in lowercase. Example: "nl"
  • This is required to ensure that the response complies with relevant laws on the display of taxes and fees.

• booker.platform: The platform from which the request is being made (Example: "desktop", "mobile", "tablet", etc).

  • This ensures that any platform-based prices and deals can be returned correctly.

2. Set travel dates

Travelling dates are mandatory for your search request.

• checkin and checkout: The guests arrival and departure dates.
• "Ensure that the date format follows YYYY-MM-DD.

3. Specify location criteria

For each request, must specify one (and only one) of the following fields to define the geographic target of the search request: region, city,district,airport and landmark.

→ Use the /common/locations endpoints to get the ID you need for the location field.

• When using landmarks, you can use the coordinates to restrict the search to a certain distance.

  1. Get the coordinates of a landmark by using locations/landmarks, or of an accommodation by using /accommodations/details.

  2. You can then set the coordinates defining the latitude and longitude of the centre of the search, and the radius (in KM) from that point defining the limit of the search.

  Example:

  {
  "coordinates": {
  "latitude": 52.378281,
  "longitude": 4.900070,
  "radius": 1
  },
  
  

• Same logic applies to accommodations id.

4. Input guest details and room allocation

You must then set the guest details and allocation:

• guests.number_of_adults: The number of adults who will be staying.
• guests.number_of_rooms: The number of rooms they need.

1. Create an array of objects under guests.allocation, one object for each room.
2. In each object:

   • In guests.children, if any children will be staying, add the age of each child who should occupy the room.

     • For example, [3,3,8,12]specifies four children, two aged 3, one aged 8 and one aged 12.
     • 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.

Make sure that the total number of:

• Objects matches the number specified in guests.number_of_rooms.
• Children allocated to rooms, and their ages, matches the information specified in guests.children.
• 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]
}

Optional fields

Optional fields allow you to enhance the search response by including additional details such as extra charges, specific products, and more.

You can optionally filter for instance by:

• accommodations - Including a list of accommodation ids. 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.

• extra_charges: To return additional information about any additional fee that must be paid on top of the base price.

  Example:

  "extras": [
  "extra_charges",
  "products"
  ],
  

Search results

Our search results are also a recommendation system. They show all the accommodations that match your search criteria based on different variables.

The search system takes prices as the main variable for the results ranking, offering the most affordable options always on higher rankings, sourced either from our Booking.com repository or in case of using Sell rates, from a third-party sister company source.

However, results can also be retrieved based on "popularity" ("Our top picks" in Booking.com website):

• If you specify either the country or region 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.