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 or region, 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.

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 and checkout: their arrival and departure dates
  • guests.number_of_adults: the number of adults who will be staying
  • guests.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 or landmark

• coordinates - An object 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.

  • 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.

• accommodations - 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.

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.

1. Create an array of objects under guests.allocation, one object for each room.
2. 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.

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

Product-level filters

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 (and deep_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.

1. Use coordinates rather than city as the destination. To obtain the latitude and longitude of the Amsterdam Central Station, call /common/locations/landmarks, using Amsterdam's id (-2140479) as an input.
2. Define the radius for the search as 1 km.
3. Add a filter for accommodation_types to include only hotels (204). You can get this id from /accommodations/constants.
4. 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 ids 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 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.