# Search - use cases **This section provides examples of various search requests and responses for common use cases. These will help you determine the fields you need for your own searches.** ## Search request examples ### Basic search request A very basic request that uses only the mandatory fields, could be: > *A couple looking for an overnight stay in Amsterdam*. 1. Obtain the `id` for Amsterdam from `/common/locations/cities`. 2. Use the returned `city` id (-2140479) as the destination in your search. 3. Specify dates and number of rooms and adults. ```json { "city": -2140479, "booker": { "platform": "desktop", "country": "gb" }, "checkin": "2026-11-10", "checkout": "2026-11-12", "guests": { "number_of_rooms": 1, "number_of_adults": 2 } } ``` ### Searching for hotel near to landmark > *A business traveller looking for an overnight stay in Amsterdam, who wants a hotel close to the Amsterdam Central Station*. For this case, use `coordinates` rather than `city` as the destination. 1. Call [/common/locations/landmarks](/demand/docs/open-api/demand-api/commonlocations/common/locations/landmarks) with Amsterdam's id (`-2140479`) to obtain the list of key landmarks in Amsterdam and coordinates. 2. Copy the `latitude` and `longitude` of Amsterdam Central Station. 3. Set the returned coordinates and `radius` to `1` km for the search. 4. Use [/accommodations/constants](/demand/docs/open-api/demand-api/accommodations/accommodations/constants) to get the id for hotels (`204`). 5. Include the returned hotel id in `accommodation_types` field. 6. Sort the results by `distance`, to prioritise hotels closest to the station. ```json { "coordinates": { "latitude": 52.378281, "longitude": 4.90007, "radius": 1 }, "accommodation_types": [204], "booker": { "platform": "desktop", "country": "nl" }, "currency": "EUR", "checkin": "2026-11-10", "checkout": "2026-11-12", "guests": { "number_of_rooms": 1, "number_of_adults": 1 }, "sort": { "by": "distance", "direction": "descending" } } ``` ### Finding rooms for a family with specific age children > *A family group is planning a holiday in Spain. They are looking for a week-long stay in mid-late August in a hotel*. The group needs 3 rooms for: * 2 parents with 2 young children, aged 2 and 3. * A single parent with two teenage children, aged 13 and 15. * 2 grandparents. To meet these requirements, apply the following filters: * `accommodation_types`: to include only hotels (`204`) * Use `guests.children` to specify the age of each child in the group. * Use `guests.allocation` to specify the desired occupancy for each room. ```json { "country": "es", "accommodation_types": [204], "booker": { "platform": "desktop", "country": "nl" }, "currency": "EUR", "checkin": "2026-08-08", "checkout": "2026-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] } } ``` #### Filtering by accommodation facilities and rating by review score > *A family group looking for a beach-front villa in Spain with an 8+ review score for mid-late August*. The group requires 2 rooms for: * 2 parents with 2 young children, aged 2 and 3. * 2 grandparents. * The parents want to play tennis. * The grandparents require air-conditioning and a shower in their room. | Filters to apply: | | | --- | --- | | `accommodation_facilities` | To include only accommodations that list tennis court (`9`) and beach front (`146`) as available facilities. | | `accommodation_types` | To include 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](/demand/docs/open-api/demand-api/accommodations/accommodations/constants). * Use `guests.children` to specify the age of each child in the group. * Use `guests.allocation` to specify the desired occupancy for each requested room. ```json { "country": "es", "accommodation_facilities": [9, 146], "accommodation_types": [213] "booker": { "platform": "desktop", "country": "nl" }, "currency": "EUR", "checkin": "2026-08-15", "checkout": "2026-08-25", "guests": { "allocation": [{ "children": [2, 3], "number_of_adults": 2 }, { "number_of_adults": 2 } ], "number_of_rooms": 2, "number_of_adults": 4, "children": [2, 3] }, "rating": { "minimum_review_score": 8 }, "room_facilities": [4, 11] } ``` ### Filtering by price range To limit accommodations to a specific price range: ```json { "booker": { "country": "nl", "platform": "desktop" }, "currency": "EUR", "checkin": "2026-08-15", "checkout": "2026-08-25", "city": -2140479, "price": { "minimum": 80, "maximum": 100 }, "guests": { "number_of_adults": 2, "number_of_rooms": 1 } } ``` ### Retrieving only top pick properties To return only top pick accommodations, you must use either `country` or `region` in the `location` field of the search request. Example using `region`: 1. Run the [common/locations/regions](/demand/docs/open-api/demand-api/commonlocations/common/locations/regions) to see the full list of region IDs for the desired country (in this case Spain). 2. Include the region id (725 for Andalusia) in your search request to get top picks for that region. ```json { "booker": { "country": "es", "platform": "desktop" }, "checkin": "2026-08-15", "checkout": "2026-08-25", "location": { "region": "725" }, "guests": { "number_of_adults": 2, "number_of_rooms": 1 } } ``` ![genius-bulb](/assets/genius-bulb.3e13976eeeabd0526f1d76bfb7de5967932211a5ef4afe526a3b0a71a7b02fb0.5e2a7131.png) Use [pagination](/demand/docs/development-guide/pagination) to load a subset of results in each request. This helps reduce load times and improves performance. ## Search response examples ### Basic response (without `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 `deep_link_url` for Booking.com mobile app users. * The `url` ```json { "id": 3882311, "currency": "GBP", "deep_link_url": "booking://hotel/3882311?affiliate_id=956509&checkin=2026-08-10&checkout=2026-08-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=2026-08-10&checkout=2026-08-12&no_rooms=1&group_adults=2&selected_currency=GBP&mcid=10" } ``` ## With both `products` and `extra_charges`request When `products` and `extra_charges` are included in the search request, the response provides a detailed breakdown of every charge applied to each product. The breakdown includes the charge type id, how it is applied, and how it is calculated. Refer to the [Accommodation pricing guide](/demand/docs/accommodations/prices-accommodations) for more details. ```json { "id": 3882311, "currency": "GBP", "deep_link_url": "booking://hotel/3882311?affiliate_id=956509&checkin=2026-05-10&checkout=2026-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_available_at_this_price": 5, "number_of_adults": 2, "policies": { "cancellation": { "free_cancellation_until": "2026-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=2026-05-10&checkout=2026-05-12&no_rooms=1&group_adults=2&selected_currency=GBP&mcid=10" } ``` ### With `extra_charges` When `extra_charges` are returned (without `products`), each result provides a breakdown of the charges applied to the price of the recommended product (or product combination). ```json { "id": 3882311, "currency": "GBP", "deep_link_url": "booking://hotel/3882311?affiliate_id=956509&checkin=2026-05-10&checkout=2026-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=2026-05-10&checkout=2026-05-12&no_rooms=1&group_adults=2&selected_currency=GBP&mcid=10" } ``` Refer to the [Accommodation pricing guide](/demand/docs/accommodations/prices-accommodations#extra-charges) for more details on extra_charges. ### Only with `products` When `products` are returned without `extra_charges`, each result provides detailed information about each product, including: * Room type. * Allocation of adults and children (with their ages). * Cancellation, meal, and payment policies. * Any deals applied. * The total amount of products at the same price. * Price details. ```json { "id": 3882311, "currency": "GBP", "deep_link_url": "booking://hotel/3882311?affiliate_id=956509&checkin=2026-05-10&checkout=2026-05-12&mcid=10", "price": { "book": 180.34, "total": 180.34 }, "products": [ { "id": "388231102_367857842_0_2_0", "children": [], "deal": null, "number_available_at_this_price": 10, "number_of_adults": 2, "policies": { "cancellation": { "free_cancellation_until": "2026-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=2026-05-10&checkout=2026-05-12&no_rooms=1&group_adults=2&selected_currency=GBP&mcid=10" } ``` ### With both `products` and `extra_charges` When `products` and `extra_charges` are included in the search request, the response provides a detailed breakdown of every charge applied to each product. The breakdown includes the charge type id, how it is applied, and how it is calculated. ```json { "id": 3882311, "currency": "GBP", "deep_link_url": "booking://hotel/3882311?affiliate_id=956509&checkin=2026-05-10&checkout=2026-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_available_at_this_price": 10, "number_of_adults": 2, "policies": { "cancellation": { "free_cancellation_until": "2026-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=2026-05-10&checkout=2026-05-12&no_rooms=1&group_adults=2&selected_currency=GBP&mcid=10" } ``` Curious to know more? * For more information on setting up search requests, explore the [Search for accommodation](/demand/docs/accommodations/search-for-available-properties) section. * Refer to the [Accommodation pricing](/demand/docs/accommodations/prices-accommodations) guide for more details about extra-charges, price breakdown and best practices.