# Search accommodation

This endpoint returns, by default, the cheapest available product for each accommodation that matches the specified search criteria. When you apply location filters using parameters such as country or region id, the results are sorted by Booking.com popularity (top_picks) instead of price.In this case, accommodations are ranked in descending order of popularity, meaning higher-ranked listings will appear earlier in the response.

Endpoint: POST /accommodations/search
Version: 3.1
Security: BearerAuth

## Header parameters:

  - `X-Affiliate-Id` (integer, required)
    Include here your Affiliate identifier number

## Request fields (application/json):

  - `24_hour_reception` (boolean)
    Filter the result based if the front desk reception is available 24/7. When specified true, the result will filter the products where front desk is available 24/7.

  - `accommodation_facilities` (array)

  - `accommodation_types` (array)

  - `accommodations` (array)

  - `airport` (string)
    A three-letter code that uniquely identifies an airport as defined by the International Air Transport Association (IATA). The full list can be obtained by calling  common/locations/airports.
    Example: "AMS"

  - `booker` (object, required)
    The booker's information.

  - `booker.country` (string, required)
    The booker country for showing the best price for that user and obeying laws regarding the display of taxes and fees.

  - `booker.platform` (string, required)
    The booker platform for showing the platform based deals and prices.
    Enum: "android", "desktop", "ios", "mobile", "tablet"

  - `booker.state` (string)
    The booker state for showing the best price for that user and obeying laws regarding the display of taxes and fees. Currently applicable only for country US.

  - `booker.travel_purpose` (string)
    The travel purpose of the booker.
    Enum: "business", "leisure"

  - `booker.user_groups` (array)
    The user groups that the booker is a member of.
    Enum: "authenticated"

  - `brands` (array)

  - `cancellation_type` (string)
    Filters the result for the cancellation type specified. Possible values are free_cancellation & non_refundable. If cancellation_type is free_cancellation, the result will contain all the products with free_cancellation.
    Enum: "free_cancellation", "non_refundable"

  - `checkin` (string, required)
    The checkin date. Must be within 500 days in the future and in the format yyyy-mm-dd.

  - `checkout` (string, required)
    The checkout date. Must be later than {checkin}. Must be between 1 and 90 days after {checkin}. Must be within 500 days in the future and in the format yyyy-mm-dd.

  - `city` (integer)
    A signed integer number that uniquely identifies a city. The full list can be obtained by calling common/locations/cities.

  - `coordinates` (object)
    Limit the result list to the specified coordinates.

  - `coordinates.latitude` (number)
    Specify a latitude (as well as a longitude and radius) to do searches around a specific location.

  - `coordinates.longitude` (number)
    Specify a longitude (as well as a latitude and radius) to do searches around a specific location.

  - `coordinates.radius` (number)
    The radius is km to search around the specified latitude and longitude.

  - `country` (string)
    A two-letter code that uniquely identifies a country. This code is defined by the ISO 3166-1 alpha-2 standard (ISO2) as described here: https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2. The full list can be obtained by calling common/locations/countries.
    Example: "nl"

  - `currency` (string)
    A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.
    Example: "EUR"

  - `district` (integer)
    A signed integer number that uniquely identifies a district. Typically, districts define known areas within a city. The full list can be obtained by calling common/locations/districts.

  - `dormitories` (string)
    This parameter specifies if the results should include dormitory beds or rooms. The default behaviour will include the dormitory beds or rooms with other results. When this flag is set to 'only', the response will only include dormitory beds or rooms. When this flag is set to 'exclude', the response will exclude dormitory beds or rooms. When this flag is set to 'include', the response will include dormitory beds or rooms with other results.
    Enum: "include", "exclude", "only"

  - `extras` (array)
    Input parameter to request for additional information about the products.
    Enum: "extra_charges", "products"

  - `guests` (object, required)
    The guest details for the request.

  - `guests.allocation` (array)
    The exact allocation of guests to rooms.

  - `guests.allocation.children` (array)
    The children ages for this room.

  - `guests.allocation.number_of_adults` (integer, required)
    The number of adults for this room.

  - `guests.children` (array)
    Array with the children ages.

  - `guests.number_of_adults` (integer, required)
    The number of adults for the search.

  - `guests.number_of_rooms` (integer, required)
    The number of rooms needed.

  - `landmark` (integer)
    A signed integer number that uniquely identifies a relevant geographical landmark, like a monument or a natural attraction. The full list can be obtained by calling common/locations/landmarks.

  - `meal_plan` (string)
    Filter the result based on the selected meal plan. Example: When specified breakfast_included, it will show the product with free breakfast.
    Enum: "all_inclusive", "breakfast_included", "full_board", "half_board"

  - `page` (string)
    Pagination token used to retrieve the next page of results. Obtained from next_page.

  - `payment` (object)
    The payment filter for the request

  - `payment.credit_card_required` (boolean)
    Filter to show accommodations which require credit card

  - `payment.timing` (string)
    This parameter specifies that the results should only return accommodation and blocks that contain the specified payment timings.
    Enum: "pay_at_the_property", "pay_online"

  - `price` (object)
    If specified, will return only results where the price per night falls in the specified range (inclusive). This filter requires that a currency is passed

  - `price.maximum` (integer)
    Set the maximum price per night, in the specified currency, or omit to indicate no upper limit.

  - `price.minimum` (integer)
    Set the minimum price per night, in the specified currency, or omit to indicate no lower limit.

  - `rating` (object)
    The rating filter for the request

  - `rating.minimum_review_score` (integer)
    Show only hotels with review_score >= that. Review score should be in the range 1 to 10.

  - `rating.stars` (array)
    Limit to accommodations with the given number(s) of stars. Stars should be in the range of 1 to 5.

  - `region` (integer)
    A signed integer number that uniquely identifies a geographical region. Regions usually define official administrative areas within a country, but may also include multiple countries and in some cases un-official but popular designations for geographical areas. An example of a region that crosses multiple countries is the Alps in Europe. The full list can be obtained by calling common/locations/regions.

  - `room_facilities` (array)

  - `rows` (integer)
    The maximum number of results to return.

  - `sort` (object)
    The sorting parameters for the response

  - `sort.by` (string)
    The way to sort your results. NOTE: When ordering by distance please make sure to specify the latitude and longitude!
    Enum: "distance", "price", "review_score", "stars"

  - `sort.direction` (string)
    The direction you wish for your sort.by parameter to be sorted in
    Enum: "ascending", "descending"

  - `travel_proud` (boolean)
    Filter the result based on if the property is LGBTQ+ friendly. When specified true, the result will filter and return only the accommodations that are Proud Certified.

## Response 200 fields (application/json):

  - `request_id` (string)
    Uniquely identifies the request. Please provide this identifier when contacting support.

  - `data` (array)

  - `data.id` (integer)
    A signed integer number that uniquely identifies an accommodation property. The full list can be obtained by calling [accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details).

  - `data.commission` (object)
    Commission details for the partner for a given accommodation

  - `data.commission.amount` (number)
    The actual commission amount for the partner.

  - `data.commission.percentage` (number)
    Percentage of the fee that will be received as commission.

  - `data.currency` (string)
    A three-letter code that uniquely identifies a monetary currency as defined by the ISO 4217 standard. The full list can be obtained by calling common/payments/currencies.
    Example: "EUR"

  - `data.deep_link_url` (string)
    A mobile app URL that directs the user to a specific page or content within the Booking.com app. The link can only be used on a device with the Booking.com app installed. It typically includes an Affiliate ID (AID) to attribute bookings to the affiliate partner when users are redirected

  - `data.price` (object)
    The price components of this product or selection of products. 'base' and 'extra_charges' are returned only when explicitly requested (via 'extras=extra_charges').

  - `data.price.base` (number)
    The base price. It does not include any extra charges.

  - `data.price.book` (number)
    The display price that must be shown to the traveller under local booker protection laws. This price includes the base accommodation cost and all charges that are legally required to be part of the displayed price. Equivalent to base + included charges.

  - `data.price.extra_charges` (object)
    The charge breakdown. Includes taxes and fees.

  - `data.price.extra_charges.excluded` (number)
    Charges not included in 'book'.

  - `data.price.extra_charges.included` (number)
    Charges included in 'book'.

  - `data.price.total` (number)
    The total price. Includes all extra charges.

  - `data.products` (array)

  - `data.products.id` (string)
    Unique ID of the product.

  - `data.products.bundle` (integer)
    The bundle ID of the product comprising of value added products.

  - `data.products.children` (array)
    The ages of the children allocated to this product.

  - `data.products.deal` (object,null)
    This specifies the deal tagging for the product.

  - `data.products.deal.discount_percentage` (integer)
    Discount percentage of the applied deal.

  - `data.products.deal.public_price` (number)
    Original price of this product, before applying any discounts.

  - `data.products.deal.tags` (array)
    The tags of all the applied deals.
    Enum: "black_friday", "limited_time_deal", "logged_in_deal", "mobile_rate", "seasonal_deal"

  - `data.products.inventory` (object)

  - `data.products.inventory.third_party` (boolean)
    Boolean value is "true" if the product is facilitated by a Booking.com partner company and "false" otherwise.

  - `data.products.inventory.type` (string)
    Type of inventory - either net or sell rates.
    Enum: "net", "sell"

  - `data.products.number_available_at_this_price` (integer,null)
    Number of rooms available at this price.

  - `data.products.number_of_adults` (integer)
    The number of adults allocated to this product.

  - `data.products.policies` (object)
    The policies for this product.

  - `data.products.policies.cancellation` (object)
    The cancellation policy for this product.

  - `data.products.policies.cancellation.free_cancellation_until` (string,null)
    Until when the order for this product can be cancelled for free.

  - `data.products.policies.cancellation.type` (string)
    The cancellation policy applicable to this product: "free_cancellation" allows a period for free cancellation, "non_refundable" means immediate loss of total amount, "special_conditions" means partly refundable.
    Enum: "free_cancellation", "non_refundable", "special_conditions"

  - `data.products.policies.meal_plan` (object)
    The meal plan policy for this product.

  - `data.products.policies.meal_plan.meals` (array)
    The meals included in the meal plan.
    Enum: "breakfast", "dinner", "lunch"

  - `data.products.policies.meal_plan.plan` (string)
    The meal plan included in this product.
    Enum: "all_inclusive", "breakfast_included", "full_board", "half_board", "no_plan"

  - `data.products.policies.payment` (object)
    Payment terms and conditions for this product.

  - `data.products.policies.payment.prepayment_required` (boolean)
    Whether prepayment is required for this product.

  - `data.products.policies.payment.timings` (array)
    The payment timings supported by this product.
    Enum: "pay_at_the_property", "pay_online_later", "pay_online_now"

  - `data.products.price` (object)
    The price components of this product. 'base' and 'extra_charges' are returned only when explicitly requested (via 'extras=extra_charges').

  - `data.products.price.base` (number)
    The base price. It does not include any extra charges.

  - `data.products.price.book` (number)
    The display price that must be shown to the traveller under local booker protection laws. This price includes the base accommodation cost and all charges that are legally required to be part of the displayed price. Equivalent to base + included charges.

  - `data.products.price.extra_charges` (object)
    The charge breakdown. Includes taxes and fees.

  - `data.products.price.extra_charges.conditional` (array)
    Charges that might apply under a specific condition.

  - `data.products.price.extra_charges.conditional.charge` (integer)
    A signed integer number that uniquely identifies an accommodation charge type. Examples of charges are: VAT, City Tax, etc. The full list can be obtained by calling accommodations/constants.

  - `data.products.price.extra_charges.conditional.condition` (integer,null)
    A signed integer number that uniquely identifies the condition ID. Find the full list in the Pricing guidelines.

  - `data.products.price.extra_charges.conditional.mode` (string)
    The mode of this charge. Determines how the price is calculated.
    Enum: "calculated_amount", "percentage", "per_day", "per_night", "per_person_per_day", "per_person_per_night", "per_person_per_stay", "per_stay"

  - `data.products.price.extra_charges.conditional.percentage` (number,null)
    The percentage of 'base' that this charge amounts to. Only applicable when 'mode' is 'percentage'.

  - `data.products.price.extra_charges.conditional.total_amount` (number)
    The total price for this charge.

  - `data.products.price.extra_charges.conditional.unit_amount` (number,null)
    The price per unit for this charge. Only applicable when 'mode' is 'per_day', 'per_night', 'per_person_per_day', 'per_person_per_night', or 'per_person_per_stay'.

  - `data.products.price.extra_charges.excluded` (array)
    Charges not included in 'book'.

  - `data.products.price.extra_charges.excluded.charge` (integer)
    A signed integer number that uniquely identifies an accommodation charge type. Examples of charges are: VAT, City Tax, etc. The full list can be obtained by calling accommodations/constants.

  - `data.products.price.extra_charges.excluded.mode` (string)
    The mode of this charge. Determines how the price is calculated.
    Enum: "calculated_amount", "incalculable", "percentage", "per_day", "per_night", "per_person_per_day", "per_person_per_night", "per_person_per_stay", "per_stay"

  - `data.products.price.extra_charges.excluded.percentage` (number,null)
    The percentage of 'base' that this charge amounts to. Only applicable when 'mode' is 'percentage'.

  - `data.products.price.extra_charges.excluded.total_amount` (number)
    The total price for this charge.

  - `data.products.price.extra_charges.excluded.unit_amount` (number,null)
    The price per unit for this charge. Only applicable when 'mode' is 'per_day', 'per_night', 'per_person_per_day', 'per_person_per_night', or 'per_person_per_stay'.

  - `data.products.price.extra_charges.included` (array)
    Charges included in 'book'.

  - `data.products.price.extra_charges.included.charge` (integer)
    A signed integer number that uniquely identifies an accommodation charge type. Examples of charges are: VAT, City Tax, etc. The full list can be obtained by calling accommodations/constants.

  - `data.products.price.extra_charges.included.mode` (string)
    The mode of this charge. Determines how the price is calculated.
    Enum: "calculated_amount", "incalculable", "percentage", "per_day", "per_night", "per_person_per_day", "per_person_per_night", "per_person_per_stay", "per_stay"

  - `data.products.price.extra_charges.included.percentage` (number,null)
    The percentage of 'base' that this charge amounts to. Only applicable when 'mode' is 'percentage'.

  - `data.products.price.extra_charges.included.total_amount` (number)
    The total price for this charge.

  - `data.products.price.extra_charges.included.unit_amount` (number,null)
    The price per unit for this charge. Only applicable when 'mode' is 'per_day', 'per_night', 'per_person_per_day', 'per_person_per_night', or 'per_person_per_stay'.

  - `data.products.price.total` (number)
    The total price. Includes all extra charges.

  - `data.products.room` (integer)
    A signed integer number that uniquely identifies an accommodation property room. The full list can be obtained by calling [accommodations/details](/demand/docs/open-api/demand-api/accommodations/accommodations/details).

  - `data.products.third_party_inventory` (boolean)
    Boolean value is "true" if the product is facilitated by a Booking.com partner company and "false" otherwise.

  - `data.url` (string)
    Internet address for the property page on Booking.com.

  - `next_page` (string,null)
    Indicates that more results are available. Use this pagination token to retrieve the next page of results (via parameter page).