# Migrating from /hotelAvailability (version 2) to /accommodations/search (v3)

## Overview

In version 2, the [hotelAvailability](https://developers.booking.com/api/technical.html?version=2.10#!/Availability/hotelAvailability) endpoint returns the cheapest available room for each hotel that matches a traveller’s search criteria.

In version 3, the equivalent endpoint is [/accommodations/search](/demand/docs/open-api/demand-api/accommodations/accommodations/search). This endpoint returns accommodations with at least one available product (or product combination) matching the search criteria for a traveller’s stay.

The search response returns:

* The `ID` of every accommodation that has at least one available product (or product combination) that matches the search criteria.
* The price of the product(s) that Booking.com recommends as the best match.
* Results sorted by popularity (also known as Top picks) if the search is by `country` or `region`.
* Optional sorting by other criteria (price, distance, etc.).


Important
**Do not assume that parameters and fields work the same way in version 3 as in version 2.**

V3 is a significant redesign of the Demand API, and many features work differently. Refer to this guide, the API reference, and your own testing to ensure a successful migration.

## Request parameter mappings

Use the following tables to migrate request parameters from v2 to v3.

### Location parameters

| v2 query parameter | v3 equivalent |
|  --- | --- |
| `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` |


To retrieve locations in v3, use the [common/locations API collection](/demand/docs/open-api/demand-api/commonlocations).

### Dates and guests

| v2 query parameter | v3 equivalent |
|  --- | --- |
| `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](/demand/docs/accommodations/search-for-available-properties#4.-input-guest-details-and-room-allocation). |
|  |  |


### Filter criteria

| v2 query parameter | v3 equivalent |
|  --- | --- |
| filter=free_cancellationfilter=non_refundable | `cancellation_type ` |
| filter=no_prepaymentfilter=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_filteroptions=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** |


Refer to the [Filtering and sorting guide](/demand/docs/accommodations/filter-sorting) for examples and best practices.

### Extra information

| v2 query parameter | V3 equivalent |
|  --- | --- |
| 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 endpoint](/demand/docs/open-api/demand-api/accommodations/accommodations/details) to return this information. |
| extras=payment_terms,extras=sustainability | **Not available** |


### General

| v2 query parameter | v3 equivalent |
|  --- | --- |
| add_filtered rate | **Not available** |
| affiliate_id | `X-Affiliate-Id ` |
| 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 | v3 equivalent |
|  --- | --- |
| 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 version 2 `order_dir` values asc and desc are not available. Use ascending and descending instead. |


Refer to the [Pagination guide](/demand/docs/development-guide/pagination) for examples and best practices.

### Response field mappings

#### Accommodation-level fields

| v2 field | v3 equivalent |
|  --- | --- |
| `hotel_id` | `id` |
| `hotel_currency_code` | `currency` |
| `hotel_url` | `url` |
| `deep_link_url` | `deep_link_url` |
| `net_price`, `price` | `price` — See the [Pricing guide](/demand/docs/accommodations/prices-accommodations). |
| Most other fields (e.g. `address`, `stars`, `review_score`, `hotel_name`, `hotel_photo`) | **Not available.**  Use [/accommodations/details endpoint](/demand/docs/open-api/demand-api/accommodations/accommodations/details) instead. |
| `cheapest_filtered_rate`, `default_language`, `sustainability`, `review_score_word`, `direct_payment` | **Not available** |


#### Product - room level fields

| v2 field | v3 equivalent |
|  --- | --- |
| `block_id` | `id` |
| `adults`, `children` | `number_of_adults`, `children` |
| `room_id` | `room` |
| `room_name`, `room_type_id`, `room_amenities` | **Not available.** Use [/accommodations/details endpoint](/demand/docs/open-api/demand-api/accommodations/accommodations/details). |
| `cancellation_type`, `refundable`, `refundable_until` | `policies.cancellation` |
| `all_inclusive`, `breakfast_included`, `full_board`, `half_board` | `policies.meal_plan` |
| `payment_options.pay_at_property`, `payment_options.pay_online` | `policies.payment.timings` |
| `extra_charge`, `net_price`, `price` | `price` — See the [Pricing guide](/demand/docs/accommodations/prices-accommodations). |
| Deal fields: `deal_tagging.deal_name`, `discount_percentage`, `public_price` | `deal` object (see [Deals](#deals-in-v2-and-v3) section) |
| `num_rooms_available_at_this_price` | **Not available.** Use `/accommodations/availability`. |
| Payment-related fields like `deposit_required`, `pay_later_collection_date`, `payment_terms.*` | **Not available.** See the [Payments guide](https://developers.booking.com/demand/docs/payments/payments-methods#authorisation-form). |
| `platform` | **Not available** |


## Deals in version 2 and version 3

In version 2, deal-related information was available through the `deal_tagging.deal_name`, `deal_tagging.discount_percentage`, and `deal_tagging.public_price` fields within the `Rooms` response schema of the /hotelAvailability endpoint.

In version 3, deal information is included in the `deal` object returned in [accommodations/search](/demand/docs/open-api/demand-api/accommodations/accommodations/search) response.
The deal object includes:

* `discount_percentage` - The total discount percentage applied to the product's public_price.
* `public_price` - The original price of the product before any discounts.
* `price.book `- The discounted price (public_price minus the discount_percentage).
* `tags` - These tags help categorise discounts and identify promotions.


Types of deals available in v3 include:

* Logged_in_deals - Exclusive offers for users meeting specific criteria.
* Deal of the day - Daily promotions with discounts on selected properties.
* Last minute deals - Discounts for bookings made shortly before check-in.
* Limited-time deals -  Offers valid for a short, predefined period, such as Black Friday.


See the [Discounts section](/demand/docs/accommodations/discounts) for more details.