/hotelAvailability - V3 migration guide
In V2, the hotelAvailability endpoint returns the cheapest available room for each hotel matching a traveller's check-in and check-out dates.
In V3, the equivalent endpoint is /accommodations/search. Use this endpoint to search for accommodations that has at least one available product that matches the search criteria for a traveller's stay.
The search response returns:
- The
IDof 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 in the request is for accommodations located in a specific
countryorregion, 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.
Use the following tables to identify how to migrate request query parameters and response fields from a V2 call to the appropriate V3 equivalent.
Attention
Do not assume that mapped parameters or fields work in exactly the same way in V3 as they did in V2.
V3 is a significant redesign of the Demand API and some things work very differently. Use this documentation, the API Reference, and your own experimentation and testing to make sure that you migrate each V2 call correctly.
Request parameter mappings
Location
| V2 query parameter | Equivalent V3 field |
|---|---|
| airport | airport |
| city_ids, countries, district_ids, landmark_ids, region_ids | city, country, district, landmark, region |
| hotel_ids | accommodations |
| latitude, longitude, radius | coordinates-> - latitude, - longitude, - radius |
Dates and guests
| V2 query parameter | Equivalent V3 field |
|---|---|
| checkin | checkin |
| checkout | checkout |
| guest_country | booker.country |
| guest_ip | Not available. Use booker.country instead. |
| no_rooms, room1..room30 | guests V3 handles allocation of guests to rooms differently to V2. See Guest details and room allocation. |
| checkin | checkin |
Filter criteria
| V2 query parameter | Equivalent V3 field |
|---|---|
| filter=free_cancellation filter=non_refundable | cancellation_type |
| filter=no_prepayment filter=sustainable | Not available |
| hotel_facility_type_ids | accommodation_facilities |
| max_price, min_price | price |
| mealplan | meal_plan |
| min_review_score, stars | rating |
| options=no_cc_filter options=show_test | Not available |
| options=no_dorms | dormitories |
| options=is_24hr | 24_hour_reception |
| property_type | accommodation_types |
| room_facility_type_ids | room_facilities |
| show_only_deals | Not available |
Extra information
| V2 query parameter | Equivalent V3 field |
|---|---|
| extras=block_payment_options | extras.products |
| extras=hotel_details extras=hotel_amenities extras=room_amenities extras=room_details extras=room_policies, | Not available. Use /accommodations/details to return this information. |
| extras=payment_terms, extras=sustainability | Not available |
General
| V2 query parameter | Equivalent V3 field |
|---|---|
| add_filtered rate | Not available |
| affiliate_id | Not available |
| currency | currency |
| language | Not available This parameter is not needed because /accommodations/search does not return any translatable data. |
| user_platform | booker.platform |
Sorting and pagination
| V2 query parameter | Equivalent V3 field |
|---|---|
| offset | page |
| rows | rows |
| order_by | sort.by - The V2 order_by values popularity and ranking are not available. - Now popularity is set by default when searching by country or region. (Not applicable to city or district.) |
| order_dir | sort.direction The V2 order_dir values asc and desc are not available. Use ascending and descending instead. |
Response schema mappings
result
| V2 field | Equivalent V3 field |
|---|---|
| address, checkin_time, cc_required, cvc_required, country, hotel_amenities, hotel_name, hotel_photo, location, postcode, review_nr, review_score, stars | Not available Use /accommodations/details to obtain this information. |
| cheapest_filtered_rate, default_language, sustainability | Not available |
| deep_link_url | deep_link_url |
| direct_payment | Not available V3 handles payments differently to V2. |
| hotel_currency_code | currency |
| hotel_id | id |
| hotel_url | url |
| net_price,price | price: V3 handles prices differently to V2. See Prices (/accommodations). |
| review_score_word | Not available Use /accommodations/constants to obtain this information. |
rooms -> products
| V2 field | Equivalent V3 field |
|---|---|
| adults | number_of_adults |
| all_inclusive, breakfast_included, full_board, half_board | policies.meal_plan |
| breakfast_cost | Not available |
| block_id | id |
| cancellation_type, refundable, refundable_until | policies.cancellation |
| children | children |
| deal_tagging.deal_name, deal_tagging.discount_percentage, deal_tagging.public_price | deal |
| platform | Not available |
| deposit_required | Not available |
| extra_charge, net_price, price | price V3 handles prices differently to V2. See Prices (/accommodations). |
| num_rooms_available_at_this_price | Not available. Use /accommodations/availability to obtain this information. |
| pay_later_collection_date, payment_terms.cancellation_description, payment_terms.name, payment_terms.prepayment_description | Not available V3 handles payments differently to V2. |
| payment_options.pay_at_property, payment_options.pay_online | policies.payment.timings |
| room_amenities, room_name, room_type_id | Not available. Use /accommodations/details to obtain this information. |
| room_id | room |
| room_policies.class, room_policies.content, room_policies.mealplan_vector | Not available |