openapi: 3.0.0 info: title: Booking.com Property API description: | The Booking.com Property API returns the full detail for a single property page: property information (name, address, review score and breakdown, images, GPS), bookable rooms with bed configuration and prices, amenities, review topics and featured reviews, an AI review summary, house rules, FAQs, and nearby places: restaurants, attractions, public transport, beaches and airports with distances. **Cross-linking**: The required `url` parameter is the `link` field of a property returned by the Booking.com API. version: 1.0.0 servers: - url: https://www.searchapi.io/api/v1 paths: /search: get: summary: Booking.com Property security: - ApiKeyAuth: [] - ApiKeyQuery: [] parameters: - name: engine in: query required: true description: Search engine to use schema: type: string enum: ["booking_property"] - name: url in: query required: true description: >- The Booking.com property page URL, obtained from the link field of a Booking.com API result. Must be a booking.com /hotel/{country}/{property}.html page, with or without a locale infix; anything else is rejected with a 400. schema: type: string - name: check_in_date in: query required: false description: >- The check-in date, format YYYY-MM-DD. Rejected with a 400 unless it is sent together with check_out_date, is a real calendar date, and is not already past in Etc/GMT+12, the last zone on earth to roll a date over. Booking prices a stay rather than a date, so the rooms array is returned only when both dates are supplied, and is omitted when the property has no availability for the requested stay. schema: type: string pattern: '^\d{4}-\d{2}-\d{2}$' - name: check_out_date in: query required: false description: >- The check-out date, format YYYY-MM-DD. Rejected with a 400 unless it is sent together with check_in_date, is a real calendar date that is not already past in Etc/GMT+12, falls strictly later than check_in_date, and leaves a stay of no more than 90 nights. schema: type: string pattern: '^\d{4}-\d{2}-\d{2}$' - name: adults in: query required: false description: >- The number of adult guests. Room rates are quoted per occupancy, so this is always sent: left unset, Booking picks its own and the same request can return different prices. schema: type: integer minimum: 1 maximum: 30 default: 2 - name: children_ages in: query required: false description: >- A comma-separated list of the children's ages, each between 0 and 17. The number of values sets the number of children; an age outside that range is a 400. schema: type: string - name: rooms in: query required: false description: >- The number of rooms to search for. Always sent, for the same reason as adults. schema: type: integer minimum: 1 maximum: 30 default: 1 - name: currency in: query required: false description: >- The ISO currency code the room prices are returned in. When omitted, Booking prices the page in its own default for the request, which is not guaranteed to be stable between calls. schema: type: string enum: ["AED", "ARS", "AUD", "AZN", "BHD", "BRL", "BGN", "CAD", "XOF", "CLP", "CNY", "COP", "CZK", "DKK", "EGP", "EUR", "FJD", "GEL", "HKD", "HUF", "INR", "IDR", "ILS", "JPY", "JOD", "KZT", "KRW", "KWD", "KGS", "LAK", "MYR", "MXN", "MDL", "NAD", "TWD", "NZD", "NOK", "OMR", "PLN", "GBP", "QAR", "RON", "RUB", "SAR", "RSD", "SGD", "ZAR", "SEK", "CHF", "THB", "TRY", "UAH", "USD", "UZS", "VND"] - name: language in: query required: false description: >- The language of the returned property content: room names, amenities, house rules and review categories. Defaults to en-us, Booking's own default English, rather than being left to Booking, so the same request returns the same language every time. en is accepted as an alias for en-us. schema: type: string enum: ["en-gb", "en-us", "de", "nl", "fr", "es", "es-ar", "ca", "it", "pt-pt", "pt-br", "no", "fi", "sv", "da", "cs", "hu", "ro", "ja", "zh-cn", "zh-tw", "pl", "el", "ru", "tr", "bg", "ar", "ko", "he", "lv", "uk", "id", "ms", "th", "et", "hr", "sk", "sr", "sl", "vi", "tl", "is", "lt", "en"] default: "en-us" - name: api_key in: query required: false description: Pass API key as query parameter schema: type: string responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/SearchResponse' '400': description: Validation Error. There is an issue with query parameters, such as missing required parameters or invalid values. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Authentication Error. The API key is missing or invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Rate Limit Exceeded. The number of allowed requests has been exceeded. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Server Error. Internal server error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: >- Timeout, or Booking answered but returned nothing usable (an unknown property, a delisted one redirected to a search page, or a page that never carried results). The body is a bare {"error": ...} rather than a search response, and the search is not billed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: securitySchemes: ApiKeyAuth: type: apiKey in: header name: Authorization description: 'Use Bearer authentication. Format: "Bearer YOUR_API_KEY"' ApiKeyQuery: type: apiKey in: query name: api_key description: Pass API key as query parameter schemas: SearchResponse: type: object properties: search_metadata: $ref: '#/components/schemas/SearchMetadata' search_parameters: $ref: '#/components/schemas/SearchParameters' property_information: $ref: '#/components/schemas/PropertyInformation' rooms: type: array description: >- Bookable room offers with rates for the requested stay. Returned only when both check_in_date and check_out_date are supplied and the property has availability; omitted otherwise. items: $ref: '#/components/schemas/Room' amenities: type: array description: >- The property's headline facilities. Read from Booking's own facility list rather than the rendered chips, which drift in wording within one language and carry neither a stable identifier nor a filter token. items: $ref: '#/components/schemas/Amenity' review_topics: type: array items: type: string description: The topics guests can filter reviews by. review_summary: $ref: '#/components/schemas/ReviewSummary' featured_reviews: type: array items: $ref: '#/components/schemas/FeaturedReview' nearby_places: type: array description: >- Surroundings grouped by category, from Booking's property-surroundings dataset. The fuller of the two beach sources: its "Beaches in the neighbourhood" group carries coordinates and transport links, and generally lists more beaches than nearby_beaches. Distances are abbreviated (750 ft, 0.7 mi). items: $ref: '#/components/schemas/NearbyPlaceGroup' nearby_beaches: type: array description: >- Beaches from Booking's trip-types dataset, which is the only source carrying a rating per beach. It is a different dataset from the beach group inside nearby_places, so the two round distances differently (800 feet vs 750 ft) and neither is a strict superset of the other. Match on beach name to combine them. items: $ref: '#/components/schemas/NearbyBeach' house_rules: $ref: '#/components/schemas/HouseRules' meals: type: array description: >- Meals the property serves, priced separately from the room. Omitted where the property serves none. items: type: object properties: type: type: string description: e.g. BREAKFAST. price: type: string extracted_price: type: number styles: type: array items: type: string cuisines: type: array items: type: string dietary_options: type: array items: type: string fine_print: type: string description: >- Booking's "fine print" block: ID and credit-card requirements, minor check-in rules and special-request caveats. Rendered-page only, and genuinely absent on some properties. faqs: type: array items: $ref: '#/components/schemas/Faq' PropertyInformation: type: object properties: property_id: type: string description: Booking's own numeric id for the property. city_id: type: string description: >- The destination id of the property's city, in the same id space as the booking_autocomplete engine's dest_id. page_name: type: string description: The property's slug in its Booking URL. property_type: type: string description: The kind of place, e.g. HOTEL, APARTMENT, HOSTEL. rating_word: type: string description: The label Booking prints beside the score, e.g. "Fabulous". Matches the search engine's field of the same name. hotel_class: type: number description: >- The property's rating out of 5, same source and semantics as the booking engine's field, so it is not lost when drilling from a search result into the property. is_self_rated: type: boolean description: Present and true when hotel_class is the property's own claim rather than an official star rating. brand: type: string description: The brand the property trades under, where it belongs to one. chain_id: type: string description: Booking's id for the operating chain, for grouping inventory by operator. is_preferred: type: boolean description: Present and true when the property is a Booking preferred partner. currency: type: string description: >- The ISO code the prices on this page are displayed in — the same code the room rates carry. Omitted when the page states no currency and the request asked for none: a bare "$" is 29 currencies and names none of them. base_currency: type: string description: >- The property's own base currency. It does not follow the `currency` parameter, so it disagrees with the prices whenever another one is requested. languages_spoken: type: array description: ISO codes of the languages the property's staff speak. items: type: string is_sustainable: type: boolean description: Present and true when the property holds a recognised sustainability certification. sustainability_certifications: type: array description: The certification names behind is_sustainable. items: type: string name: type: string description: The property name. description: type: string description: The property description. address: type: string description: The property address, as a single pre-joined line. street: type: string description: The street line of the address. Same key the search engine publishes. city: type: string region: type: string postal_code: type: string country_code: type: string description: Two-letter country code. Same key the search engine publishes. country: type: string description: The country's display name, as Booking prints it (e.g. "Croatia", "UK"). rating: type: number description: The overall guest review score, on Booking's 0-10 scale. max_rating: type: integer description: The top of the rating scale, read from the page itself. Always 10 on Booking. reviews: type: integer description: The total number of guest reviews. review_breakdown: type: object description: >- Per-category guest scores, keyed by Booking's own category id (staff, clean, comfort, location, services, value, free_wifi). The ids are stable across languages, so the keys do not change with language. Each value carries the score, the translated label, and the city-average band Booking publishes beside it. additionalProperties: type: object properties: score: type: number description: The category score out of 10. label: type: string description: The translated category name, which does change with language. city_average_low: type: number description: Low end of the city-average band Booking prints beside the score. city_average_high: type: number description: High end of the city-average band. check_in_time: type: string description: The earliest check-in time. check_out_time: type: string description: The latest check-out time. gps_coordinates: type: object properties: latitude: type: number longitude: type: number url: type: string description: The canonical property page URL. thumbnail: type: string description: The hero image URL. images: type: array items: type: string description: >- The full accommodation gallery, every image at the same max1024x768 variant. Room photos are included, since Booking publishes them as gallery members too. Room: type: object properties: position: type: integer description: The position of the room in the list. name: type: string description: The room type name. bed_configuration: type: string description: The bed setup of the room. price: type: string description: The room price for the stay. extracted_price: type: number description: The numeric room price. currency: type: string description: >- The ISO code the rate is displayed in — the same code as `property_information.currency`. Not `property_information.base_currency`, which is the property's own base currency and does not follow the `currency` parameter. room_size: type: number description: The room's floor area. room_size_unit: type: string max_guests: type: integer max_children: type: integer bathrooms: type: integer is_smoking: type: boolean description: Present and true when the room is a smoking room. Omitted otherwise. bed_options: type: array description: >- Every bed setup the room can be made up as, not just the one the rate row prints. Each entry is one configuration, listing its beds. items: type: array items: type: object properties: type: type: string count: type: integer is_partner_offer: type: boolean description: >- Present and true when the rate is resold by an external partner rather than offered by Booking.com directly. Partner rates carry their own tax and cancellation terms, and describe themselves rather than inheriting the room type of the direct rates around them. They are not joined to the property's room detail, so room_size, max_guests, bathrooms and bed_options are omitted on them. Omitted on direct rates. Amenity: type: object properties: name: type: string description: The facility's name in the requested language. slug: type: string description: Booking's own identifier for the facility, stable across languages and properties. value: type: string description: >- The facet token that filters a Booking.com API search on this facility (e.g. hotelfacility=11), usable directly in that engine's filters parameter. ReviewSummary: type: object description: >- An AI-generated summary of guest reviews. Booking ships it either as typed pros/cons bullets or as a prose block, so a response carries `pros`/`cons` or `highlights`, not both. properties: summarized_reviews: type: integer description: >- How many reviews the summary was written from. This is the summary's own sample size, not the property's review count — read property_information.reviews for that. language: type: string description: The language the summary was written in. highlights: type: array description: The prose form of the summary, one entry per bullet. items: type: string pros: type: array items: $ref: '#/components/schemas/ReviewSummaryBullet' cons: type: array items: $ref: '#/components/schemas/ReviewSummaryBullet' ReviewSummaryBullet: type: object properties: text: type: string description: The claim the bullet makes. mentions: type: integer description: How many reviews back the claim. sentiment: type: string description: positive, negative or mixed. A mixed bullet in `cons` is not a complaint. FeaturedReview: type: object description: >- A highlighted guest review. Read from the page's own review data rather than the rendered quote, which Booking clamps behind a Read more control. properties: author: type: string description: The reviewer's name. country_code: type: string description: The reviewer's two-letter country code. title: type: string description: The review's headline. liked: type: string description: What the guest said they liked. Present on most reviews. disliked: type: string description: What the guest said they disliked. Omitted when they raised nothing. rating: type: number description: The score this guest gave, on Booking's 0-10 scale. language: type: string travel_type: type: string description: e.g. Couple, Family With Young Children, Solo Traveller. trip_type: type: string description: e.g. Leisure, Business. NearbyPlaceGroup: type: object properties: category: type: string description: The surroundings category (e.g. "Restaurants & cafes", "Top attractions"). places: type: array items: $ref: '#/components/schemas/NearbyPlace' NearbyPlace: type: object properties: name: type: string description: The place name. type: type: string description: The place classification (e.g. Restaurants, Beaches). cuisine: type: string description: The cuisine type, for dining places. distance: type: string description: The localized distance from the property. gps_coordinates: type: object properties: latitude: type: number longitude: type: number transportations: type: array description: >- How to reach the place. Where Booking publishes both, walking and driving are returned side by side rather than only its preferred mode. items: type: object properties: type: type: string enum: ["Walking", "Driving", "Public transport"] description: The commute mode (e.g. Walking, Driving). duration: type: string description: The localized commute time. distance: type: string description: The localized commute distance. extracted_distance: type: integer description: >- The commute distance in metres, always metric whatever unit `distance` is localized to. NearbyBeach: type: object properties: name: type: string description: The beach name. distance: type: string description: The localized distance from the property. rating: type: number description: The beach review score, on Booking's 0-10 scale. HouseRules: type: object properties: check_in: type: string description: The check-in time range. check_out: type: string description: The check-out time range. minimum_check_in_age: type: integer description: The minimum age required to check in. age_restriction: type: string description: The check-in age restriction phrase. quiet_hours: type: string description: The quiet hours policy. curfew: type: string description: The curfew policy. smoking: type: string description: The smoking policy. parties: type: string description: The parties/events policy. group_policy: type: string description: The policy for group bookings. payment_methods: type: array items: type: string description: The accepted payment methods. is_cash_accepted: type: boolean description: >- Present and true when the property takes cash. Booking publishes this as a pseudo-card in the accepted-card list rather than as a flag, so it is returned here instead of as a payment method called "Cash only". Omitted otherwise. children: type: object description: The property's children and extra-bed policy. properties: are_children_allowed: type: boolean description: Present and true when children may stay. Omitted otherwise. minimum_age: type: integer description: The youngest age the property accepts, when it sets one. are_cribs_allowed: type: boolean description: Present and true when cribs are available. Omitted otherwise. are_extra_beds_allowed: type: boolean description: Present and true when extra beds are available. Omitted otherwise. pets: type: object description: The property's pet policy. properties: are_pets_allowed: type: boolean description: Present and true when pets may stay. Omitted otherwise. charges: type: string description: >- How pets are charged, e.g. "charges may apply", "free of charge", "not applicable". Faq: type: object properties: question: type: string description: The traveller's question. answer: type: string description: The answer. asked_date: type: string description: The date the question was asked. answered_date: type: string description: The date the question was answered. SearchMetadata: type: object required: [id, status, created_at] properties: id: type: string description: "Unique identifier for the search request" status: type: string description: "Status of the search request" created_at: type: string format: date-time description: "Timestamp when the search was created" request_time_taken: type: number description: "Time taken to make the request in seconds" parsing_time_taken: type: number description: "Time taken to parse the results in seconds" total_time_taken: type: number description: "Total time taken for the search in seconds" request_url: type: string description: "Booking.com URL for this search" html_url: type: string description: "URL to view HTML results" json_url: type: string description: "URL to view JSON results" SearchParameters: type: object properties: engine: type: string url: type: string check_in_date: type: string check_out_date: type: string adults: type: integer children_ages: type: string rooms: type: integer currency: type: string language: type: string ErrorResponse: type: object required: [error] properties: error: type: string description: Error message describing what went wrong