# v3.2 Accommodation quick guide **Follow this quick guide to start playing with our v3.2 Accommodation API collection in your client application**. div strong ⏱️ Estimated time to complete: 15 - 30 minutes span v3.2 br This quick guide shows the minimum steps needed to integrate the [v3.2 Demand API accommodation endpoints](/demand/docs/open-api/3.2/demand-api) ## Steps Follow these steps to test a basic example: > *A traveller searches for a 2-night stay in Amsterdam for 2 adults in 1 room.* ### 1. Search for accommodation To find properties that match the use case search criteria: → Use the [accommodations/search](/demand/docs/open-api/3.2/demand-api/accommodations/accommodations/search) endpoint. * By default, the response returns the cheapest available product per accommodation. * When filtering by broader locations such as `country` or `region`, results are ranked by Booking.com popularity (top picks) rather than strictly by price. **Required fields** The following fields are mandatory: * `booker` * `checkin` * `checkout` * `guests` **Example request:** ```json { "country": "nl", "booker": { "country": "nl", "platform": "mobile" }, "extras": [ "extra_charges", "products" ], "checkin": "2026-11-06", "checkout": "2026-11-08", "guests": { "number_of_rooms": 1, "number_of_adults": 2 }, "sort": { "by": "price", "direction": "ascending" } } ``` details summary More details You must specify at **least one location parameter**. Supported options include: * `city` — city ID * `country` — ISO 3166-1 alpha-2 lowercase * `region` * `district` * `airport` * `landmark` * `coordinates` * `accommodations` — specific accommodation IDs (max 100) Get location IDs from [location endpoints](/demand/docs/open-api/3.2/demand-api/commonlocations) **Filters** Use the filters object to refine results. For example: * price (per night range — requires currency) * rating (review score and/or stars) * meal_plan * cancellation_type * payment timing * accommodation_types * accommodation_facilities * room_facilities * travel_proud * sustainability_certification * See the [accommodation search guide](/demand/docs/accommodations/search-for-available-properties/) for examples and tips on creating search requests. * See the [Data conventions guide](/demand/docs/development-guide/code-conventions) for date/times formats. * Check the [v3.2 Filtering guide](/demand/docs/accommodations/v3.2/filter-sorting) **Example response:** The response contains a list of accommodations that match the specified search criteria, including the price and url to Booking.com property page. ```json { "request_id": "01fr9ez700exycb98w90w5r9sh", "data": [ { "id": 10507360, "currency": { "accommodation": "EUR", "booker": "EUR" }, "deep_link_url": "booking://hotel/10507360?affiliate_id=956509&checkin=2026-11-06&checkout=2026-11-08&mcid=10", "price": { "base": { "accommodation_currency": 1081.49, "booker_currency": 1081.49 }, "charges": [], "display": { "accommodation_currency": 1260.52, "booker_currency": 1260.52 }, "total": { "accommodation_currency": 1260.52, "booker_currency": 1260.52 } }, "products": [ { "id": "10507360_95127794_2_0_0", "number_of_adults": 2, "price": { "total": { "accommodation_currency": 1260.52, "booker_currency": 1260.52 } } } ], "url": "https://www.booking.com/hotel/nl/example.html?aid=956509&checkin=2026-11-06&checkout=2026-11-08&group_adults=2&no_rooms=1" } ], "metadata": { "next_page": "eyJwYWdlIjoyfQ==" } } ``` Keep the accommodation `id` for the next step. Try it yourself ### 2. Get accommodation details Use this step to retrieve static property information (not availability or pricing). Availability and prices must be retrieved via /accommodations/availability. → Call [/accommodations/details](/demand/docs/open-api/3.2/demand-api/accommodations/accommodations/details) using the accommodation `id` from the search response. You must provide at least one of the following parameters: * `accommodations` * `airport` * `city` * `country` * `region` You can query up to 100 accommodation IDs in a single request. **Example request:** ```json { "accommodations": [ 10507360 ], "extras": [ "description" ], "languages": [ "en-gb" ] } ``` details summary More details **Languages** * You can request multiple languages using IETF language tags (e.g. en-gb, zh-cn). * If content is not available in a requested language, English is returned by default. **Using extras** * The extras array controls which additional datasets are returned. * Common `extras` values include: `description`, `photos`, `facilities`, `policies`, `rooms`, `bundles`, `payment`. Example: ```json "extras": [ "description", "photos", "facilities", "payment" ], ``` Check the ["Extras" use guide](/demand/docs/accommodations/look-accommodation-details#extras-information). **Pagination** * Use `rows` to control the number of results (max 1000). Try it yourself **Example response:** The response contains all static information about the selected accommodation, including: * Name and translated content. * Location and coordinates. * Contact details. * Facilities and photos (if requested via extras). * Policies and payment configuration. * Ratings and ranking. * URLs for web and app redirects. ```json { "request_id": "01k2kv6g4de00n4cw4cvr4v5bm", "data": [ { "id": 10507360, "name": { "en-gb": "Demand API Sandbox Hotel Orion" }, "accommodation_type": 204, "booker_address_required": false, "checkin_checkout_times": { "checkin_from": "12:00:00", "checkin_to": "20:00:00", "checkout_from": "08:00:00", "checkout_to": "12:00:00" }, "contacts": { "general": { "email": "demand.api.dev@booking.com", "telephone": "+31207125609" }, "reservations": null }, "currency": "EUR", "is_genius": true, "location": { "address": { "en-gb": "Oosterdoksstraat 154" }, "city": -2140479, "coordinates": { "latitude": 52.376388, "longitude": 4.90919 }, "country": "nl", "districts": [ 145, 9173 ], "postal_code": "1011 DL", "regions": [ 1010 ] }, "meal_prices": { "breakfast": 12, "lunch": 10, "dinner": 15 }, "number_of_rooms": 300, "ranking": 4703915, "rating": { "number_of_reviews": 0, "preferred": true, "review_score": null, "stars": 5, "stars_type": "official" }, "spoken_languages": [ "en-gb" ], "url": { "web": "https://www.booking.com/hotel/nl/demand-api-sandbox-orion.html?aid=956509", "app": "booking://hotel/10507360?affiliate_id=956509" } ] } ``` * Use this information to enrich your property listing page (photos, facilities, descriptions, policies, payment methods, etc.). * To retrieve live prices and available products, continue with the availability step. ### 3. Get availability and prices Use this step to retrieve **real-time availability, prices, and extra charges** for the selected accommodations. → Call the [accommodations/availability endpoint](/demand/docs/open-api/3.2/demand-api/accommodations/accommodations/availability) using the `accommodation` id from the previous step. **Mandatory fields:** `accommodations`, `booker`, `checkin`, `checkout`, and `guests`. Maximum 50 accommodation IDs per request. **Example request:** ```json { "accommodations": [10507360], "booker": { "country": "nl", "platform": "desktop" }, "checkin": "2026-11-06", "checkout": "2026-11-08", "guests": { "number_of_adults": 2, "number_of_rooms": 1 }, "extras": [ "extra_charges" ], "filters": { "meal_plan": "breakfast_included", "cancellation_type": "free_cancellation" } } ``` details summary More details * Use `Filters:` Apply criteria like meal_plan, cancellation_type, or other product-specific filters. **Example response** The response provides **available products, prices, policies, and a recommendation** for the best option. ```json { "request_id": "01k2m3js8k6rkgb09vehxcfbjy", "data": [ { "id": 10507360, "currency": { "accommodation": "EUR", "booker": "EUR" }, "deep_link_url": "booking://hotel/10507360?affiliate_id=!AFFILIATE_ID!&checkin=2026-02-02&checkout=2026-02-10", "products": [ { "id": "1050736003_405384551_2_0_0", "bundle": null, "deal": { "discount_percentage": 3, "public_price": 98.2, "tags": ["mobile_rate"] }, "maximum_occupancy": { "adults": 4, "children": null, "total": 4 }, "number_available": 6, "policies": { "cancellation": { "free_cancellation_until": "2026-10-31T00:00:00+00:00", "type": "free_cancellation", "schedule": [ { "from": "now", "price": { "accommodation_currency": 0, "booker_currency": 0 } }, { "from": "2026-10-31T00:00:00+00:00", "price": { "accommodation_currency": 95.38, "booker_currency": 95.38 } } ] }, "meal_plan": { "meals": ["breakfast"], "plan": "breakfast_included" }, "payment": { "timings": ["pay_at_the_property"] } }, "price": { "base": { "accommodation_currency": 95.38, "booker_currency": 95.38 }, "chargeable_online": { "accommodation_currency": 95.38, "booker_currency": 95.38 }, "total": { "accommodation_currency": 95.38, "booker_currency": 95.38 } }, "room": "1050736003" } ], "recommendation": { "price": { "base": { "accommodation_currency": 95.38, "booker_currency": 95.38 }, "chargeable_online": { "accommodation_currency": 95.38, "booker_currency": 95.38 }, "total": { "accommodation_currency": 95.38, "booker_currency": 95.38 } }, "products": [ { "id": "1050736003_405384551_2_0_0", "children": [], "number_of_adults": 2, "price": { "base": { "accommodation_currency": 95.38, "booker_currency": 95.38 }, "chargeable_online": { "accommodation_currency": 95.38, "booker_currency": 95.38 }, "total": { "accommodation_currency": 95.38, "booker_currency": 95.38 } } } ] }, "url": "https://www.booking.com/hotel/nl/demand-api-sandbox-orion.html?aid=!AFFILIATE_ID!&checkin=2026-11-06&checkout=2026-11-08&no_rooms=1&group_adults=2" } ] } ``` > ![genius-bulb](/assets/genius-bulb.3e13976eeeabd0526f1d76bfb7de5967932211a5ef4afe526a3b0a71a7b02fb0.5e2a7131.png) Use the `recommendation` field to highlight the best-priced option for your user. Prices and availability are dynamic and may change between search and booking. Always confirm before proceeding. Try it yourself ### 4. Handle the booking Choose your integration type: * **Search, look and redirect** → Redirect travelleres to the Booking.com `url` provided in the availability response. * **Search, look and book** → Book within your application using [/orders/preview](/demand/docs/open-api/3.2/demand-api/orders/orders/preview) and [/orders/create](/demand/docs/open-api/3.2/demand-api/orders/orders/create) For Search, look and book, you must have: * An approved business case. * A signed partner agreement. Orders guides * See the [Orders creation guide](/demand/docs/orders-api/order-preview-create) to learn how to proceed the booking. ## Best practices ✓ Always include your API key token and `X-Affiliate-Id` in every request. ✓ Use the correct [data conventions](/demand/docs/development-guide/code-conventions) in your requests to avoid errors. ✓ Store static location data (cities, countries, etc) to reduce API calls. ## Next steps Congratulations, by now you know the basics of how to use the key accommodation endpoints! * See the [Search, look and book tutorial](/demand/docs/accommodations/accommodation-tutorial) for full step by step guide. * Refer to the [Orders](/demand/docs/open-api/3.2/demand-api/orders) and [payments](/demand/docs/payments/how-to) guides to make your first order.