Logo SearchApi

Booking.com API Documentation

GET   /api/v1/search?engine=booking
OpenAPI Initiative Download OpenAPI Spec

The Booking.com API returns real-time property search results for a destination and stay. Each result includes the property title, address parts, star rating, guest review score, price and per-night rate, bed configuration, availability, and boolean flags such as free cancellation. The response also exposes grouped, response-derived filters you can feed back into the request, along with pagination and total-result metadata.

API Parameters

Search Query

  • Name
    q
    Required
    Optional
    Description

    The destination to search for: a city, region, district, landmark, or specific property name (e.g. Dubrovnik). Optional when both dest_id and dest_type are supplied, since those identify the destination on their own.

  • Name
    dest_id
    Required
    Optional
    Description

    The Booking destination id, obtained from the Booking Autocomplete API. Combine with dest_type to target an exact destination instead of relying on the q text match. The two identify a destination only as a pair, so either both are sent or neither is; one on its own is rejected with a 400.

  • Name
    dest_type
    Required
    Optional
    Description

    The type of the dest_id destination, returned alongside it by the Autocomplete API. One of city, region, country, district, hotel, airport or landmark. A hotel destination searches that property's area with the property ranked first, rather than returning it alone. Must be sent together with dest_id; one without the other is a 400.

Date Range

  • Name
    check_in_date
    Required
    Optional
    Description

    The check-in date in YYYY-MM-DD format. It is 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 time zone on earth to roll a date over. Prices are quoted for a specific stay, so price, extracted_price, nightly_price and extracted_nightly_price are returned only when a date range (or the flexible-date parameters) is supplied. A dateless search returns property metadata without pricing.

  • Name
    check_out_date
    Required
    Optional
    Description

    The check-out date in YYYY-MM-DD format. It is 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.

  • Name
    flex_window
    Required
    Optional
    Description

    Enables flexible-date search, widening the stay by ± the given number of days around check_in_date / check_out_date. Supported values: 1, 2, 3, 7.

Flexible Dates

  • Name
    flex_months
    Required
    Optional
    Description

    Search whole months instead of fixed dates, Booking's “When do you want to go?”. A comma-separated list of up to 3 months in YYYY-MM format (e.g. 2026-09,2026-10,2026-11). Must be used together with flex_stay_length, and cannot be combined with check_in_date, check_out_date or flex_window.

  • Name
    flex_stay_length
    Required
    Optional
    Description

    How long the stay should be, per Booking's “How long do you want to stay?”. One of weekend, week, month, or a number of nights between 1 and 30. Required when flex_months is set.

  • Name
    flex_start_day
    Required
    Optional
    Description

    The day of the week the stay starts on: monday … sunday. Booking always pins flexible searches to a single start weekday, so a default is applied when this is omitted; results only include stays beginning on that day.

Guests

  • Name
    adults
    Required
    Optional
    Description

    The number of adult guests. An integer between 1 and 30.

  • Name
    children_ages
    Required
    Optional
    Description

    A comma-separated list of the children's ages, each between 0 and 17 (e.g. 5,8). The number of values sets the number of children; an age outside that range is a 400.

  • Name
    rooms
    Required
    Optional
    Description

    The number of rooms to search for. An integer between 1 and 30.

Sorting

  • Name
    sort_by
    Required
    Optional
    Description

    The ordering of the property results. Unset by default: with no sort_by, no ordering parameter is sent and none is echoed back in search_parameters, and Booking applies its own ordering, which is by popularity. Available options:

    • popularity
    • price_low_to_high
    • review_score
    • stars_high_to_low
    • stars_low_to_high
    • distance

Filters

  • Name
    filters
    Required
    Optional
    Description

    A comma-separated list of facet tokens to refine the results. Each token is the value of an option in the response's filters block (e.g. class=5 for 5-star properties, fc=2 for free cancellation). Combine multiple tokens with commas. Same-group tokens broaden the results (OR), cross-group tokens narrow them (AND). The price group is a range rather than a checkbox: it reports min, max and currency alongside a full-range token, so you can substitute your own bounds as price=USD-300-2000-1.

Localization

  • Name
    currency
    Required
    Optional
    Description

    The ISO currency code the prices are returned in (e.g. EUR, GBP). Check the full list of supported Booking.com currency values. When omitted, Booking prices the results in its own default for the request, which is not guaranteed to be stable between calls.

  • Name
    language
    Required
    Optional
    Description

    The interface language of the search (e.g. en-us, de, fr). Booking encodes it in the request path, so the value you send is the language you get back. Check the full list of supported Booking.com language values. Affects result language and number formatting.

Pagination

  • Name
    page
    Required
    Optional
    Description

    The results page to retrieve. Booking pages in blocks of 25, though a page may render a few more or fewer; use the pagination.next_page value from the response to page forward. Requesting a page past the last one returns an empty properties array together with search_information.total_results. Not supported together with flex_months and flex_stay_length.

Engine

  • Name
    engine
    Required
    Required
    Description

    Parameter defines an engine that will be used to retrieve real-time data. It must be set to booking.

API key

  • Name
    api_key
    Required
    Required
    Description

    The api_key authenticates your requests. Use it as a query parameter (https://www.searchapi.io/api/v1/search?api_key=YOUR_API_KEY) or in the Authorization header (Bearer YOUR_API_KEY).

Zero Data Retention

  • Name
    zero_retention
    Enterprise Only
    Enterprise Only
    Required
    Optional
    Description

    Set this parameter to true to disable all logging and persistent storage. No request parameters, HTML, or JSON responses are stored or logged. Suitable for high-compliance use cases. Debugging and support may be limited while enabled.

API Examples

Property Search

Property Search

A full response for a destination and stay: properties, grouped filters, pagination, and search_information with the total result count.

GET
https://www.searchapi.io/api/v1/search?adults=2&check_in_date=2026-10-02&check_out_date=2026-10-09&engine=booking&q=Dubrovnik
Request
import requests

url = "https://www.searchapi.io/api/v1/search"
params = {
  "engine": "booking",
  "q": "Dubrovnik",
  "check_in_date": "2026-10-02",
  "check_out_date": "2026-10-09",
  "adults": 2
}

response = requests.get(url, params=params)
print(response.text)
Response
{
  "search_metadata": {
    "id": "search_BxR6dazVoAVkFlzv3Ewvbj9G",
    "status": "Success",
    "created_at": "2026-08-25T16:03:20Z",
    "request_time_taken": 2.67,
    "parsing_time_taken": 0.11,
    "total_time_taken": 2.78,
    "request_url": "https://www.booking.com/searchresults.en-us.html?ss=Dubrovnik&checkin=2026-09-11&checkout=2026-09-18&group_adults=2&no_rooms=1&group_children=0&offset=0&lang=en-us",
    "html_url": "https://www.searchapi.io/api/v1/searches/search_BxR6dazVoAVkFlzv3Ewvbj9G.html",
    "json_url": "https://www.searchapi.io/api/v1/searches/search_BxR6dazVoAVkFlzv3Ewvbj9G"
  },
  "search_parameters": {
    "engine": "booking",
    "q": "Dubrovnik",
    "check_in_date": "2026-09-11",
    "check_out_date": "2026-09-18",
    "adults": 2,
    "rooms": 1,
    "page": 1,
    "language": "en-us"
  },
  "search_information": {
    "total_results": 270,
    "destination": {
      "name": "Dubrovnik",
      "country_code": "hr",
      "dest_id": "-79996",
      "dest_type": "city"
    }
  },
  "filters": [
    {
      "category": "price",
      "label": "Your budget (per night)",
      "options": [
        {
          "value": "price=USD-30-500-1",
          "name": "Your budget (per night)",
          "min": 30,
          "max": 500,
          "currency": "USD"
        },
        "..."
      ]
    },
    "..."
  ],
  "properties": [
    {
      "position": 1,
      "property_id": "19766",
      "city_id": "-79996",
      "title": "Valamar Argosy Hotel",
      "link": "https://www.booking.com/hotel/hr/argosydubrovnik.html",
      "neighborhood": "Babin Kuk",
      "distance": "2.7 miles from downtown",
      "gps_coordinates": {
        "latitude": 42.66106779150847,
        "longitude": 18.0634331703186
      },
      "street": "Iva Dulčića 140",
      "city": "Dubrovnik",
      "country_code": "hr",
      "extracted_distance": 2.7,
      "distance_unit": "mi",
      "hotel_class": 4,
      "rating": 8.8,
      "max_rating": 10,
      "rating_word": "Excellent",
      "reviews": 1686,
      "price": "$2,326",
      "extracted_price": 2326,
      "nightly_price": "$332",
      "extracted_nightly_price": 332,
      "currency": "USD",
      "original_price": "$2,589",
      "extracted_original_price": 2589,
      "taxes_and_charges": "$346",
      "extracted_taxes_and_charges": 346,
      "stay_summary": "1 week, 2 adults",
      "top_review_category": {
        "name": "Comfort",
        "score": 9.2
      },
      "room_type": "Superior Room for 2",
      "bed_configuration": "2 twin beds",
      "beds": 2,
      "meal_plan": "Breakfast included",
      "beach_distance": "1,000 feet from beach",
      "nearby_beaches": [
        "Copacabana Beach",
        "..."
      ],
      "is_sustainable": true,
      "sustainability_certifications": [
        "Travelife for Accommodation",
        "..."
      ],
      "free_cancellation_until": "2026-09-08T22:00:00Z",
      "is_preferred": true,
      "has_free_cancellation": true,
      "thumbnail": "https://cf.bstatic.com/xdata/images/hotel/square240/173082034.webp?k=dbeb76206a0b5f896fdd4dda0e832ddae8f91084094325fbee9f90b6d634b9c9&o=",
      "thumbnail_hd": "https://cf.bstatic.com/xdata/images/hotel/square600/173082034.webp?k=dbeb76206a0b5f896fdd4dda0e832ddae8f91084094325fbee9f90b6d634b9c9&o="
    },
    "..."
  ],
  "pagination": {
    "current_page": 1,
    "next_page": 2
  }
}

Filters

Filters

Each option's value is a facet token (e.g. class=5) usable directly in the filters request parameter, and count is the number of matching properties.

GET
https://www.searchapi.io/api/v1/search?adults=2&check_in_date=2026-10-02&check_out_date=2026-10-09&engine=booking&filters=class%3D5&q=Dubrovnik
Request
import requests

url = "https://www.searchapi.io/api/v1/search"
params = {
  "engine": "booking",
  "q": "Dubrovnik",
  "check_in_date": "2026-10-02",
  "check_out_date": "2026-10-09",
  "adults": 2,
  "filters": "class=5"
}

response = requests.get(url, params=params)
print(response.text)
Response
{
  "filters": [
    {
      "category": "popular",
      "options": [
        {
          "value": "roomfacility=11",
          "name": "Air conditioning",
          "count": 31
        },
        "..."
      ]
    },
    "..."
  ]
}

Flexible Dates

Flexible Dates

Search whole months instead of fixed dates. search_information.flexible_dates echoes back the range Booking actually applied. Use it to confirm the flexibility took effect, since a rejected range still returns a full page of properties.

GET
https://www.searchapi.io/api/v1/search?engine=booking&flex_months=2026-11%2C2026-12&flex_stay_length=weekend&q=Dubrovnik
Request
import requests

url = "https://www.searchapi.io/api/v1/search"
params = {
  "engine": "booking",
  "q": "Dubrovnik",
  "flex_months": "2026-11,2026-12",
  "flex_stay_length": "weekend"
}

response = requests.get(url, params=params)
print(response.text)
Response
{
  "search_metadata": {
    "id": "search_Rz4KNQmOp60YHV9aoyWl8DBv",
    "status": "Success",
    "created_at": "2026-08-25T16:03:40Z",
    "request_time_taken": 3.04,
    "parsing_time_taken": 0.08,
    "total_time_taken": 3.13,
    "request_url": "https://www.booking.com/searchresults.en-us.html?ss=Dubrovnik&group_adults=2&no_rooms=1&group_children=0&offset=0&efdco=1&ltfd=5:1:10-2026_11-2026:1:&lang=en-us",
    "html_url": "https://www.searchapi.io/api/v1/searches/search_Rz4KNQmOp60YHV9aoyWl8DBv.html",
    "json_url": "https://www.searchapi.io/api/v1/searches/search_Rz4KNQmOp60YHV9aoyWl8DBv"
  },
  "search_parameters": {
    "engine": "booking",
    "q": "Dubrovnik",
    "adults": 2,
    "rooms": 1,
    "flex_months": "2026-10,2026-11",
    "flex_stay_length": "weekend",
    "page": 1,
    "language": "en-us"
  },
  "search_information": {
    "total_results": 553,
    "destination": {
      "name": "Dubrovnik",
      "country_code": "hr",
      "dest_id": "-79996",
      "dest_type": "city"
    },
    "flexible_dates": {
      "months": [
        "2026-10",
        "2026-11"
      ],
      "nights": 1,
      "start_day": "friday"
    }
  },
  "filters": [
    {
      "category": "price",
      "label": "Your budget (per night)",
      "options": [
        {
          "value": "price=USD-40-400-1",
          "name": "Your budget (per night)",
          "min": 40,
          "max": 400,
          "currency": "USD"
        },
        "..."
      ]
    },
    "..."
  ],
  "properties": [
    {
      "position": 1,
      "property_id": "21338",
      "city_id": "-79996",
      "title": "Hilton Imperial Dubrovnik",
      "link": "https://www.booking.com/hotel/hr/hilton-imperial-dubrovnik.html",
      "distance": "0.2 miles from downtown",
      "gps_coordinates": {
        "latitude": 42.64264059235872,
        "longitude": 18.10469627380371
      },
      "street": "Marijana Blazica 2",
      "city": "Dubrovnik",
      "country_code": "hr",
      "extracted_distance": 0.2,
      "distance_unit": "mi",
      "hotel_class": 5,
      "rating": 9.1,
      "max_rating": 10,
      "rating_word": "Wonderful",
      "reviews": 906,
      "price": "$171",
      "extracted_price": 171,
      "nightly_price": "$171",
      "extracted_nightly_price": 171,
      "currency": "USD",
      "taxes_and_charges": "$22",
      "extracted_taxes_and_charges": 22,
      "stay_summary": "1 night, 2 adults",
      "top_review_category": {
        "name": "Location",
        "score": 9.8
      },
      "room_type": "Twin Room",
      "bed_configuration": "2 twin beds",
      "check_in_date": "2026-11-20",
      "check_out_date": "2026-11-21",
      "nights": 1,
      "beds": 2,
      "meal_plan": "Breakfast included",
      "beach_distance": "400 feet from beach",
      "nearby_beaches": [
        "Beach Šulić",
        "..."
      ],
      "is_sustainable": true,
      "sustainability_certifications": [
        "ISO 14001:2015 Environmental management system",
        "..."
      ],
      "is_guest_favorite": true,
      "is_preferred": true,
      "thumbnail": "https://cf.bstatic.com/xdata/images/hotel/square240/856632857.webp?k=b91079f358ac194e763078e46de082ac0fc67696f66b5775e2cbe7a1c2fed433&o=",
      "thumbnail_hd": "https://cf.bstatic.com/xdata/images/hotel/square600/856632857.webp?k=b91079f358ac194e763078e46de082ac0fc67696f66b5775e2cbe7a1c2fed433&o="
    },
    "..."
  ],
  "pagination": {
    "current_page": 1,
    "next_page": 2
  }
}