GET

Search by URL API

Search for hotels using a Booking.com search results URL directly from your browser.

Copy for your AI agent

Paste into Claude, ChatGPT, Cursor or Copilot — endpoint, parameters, response fields and a curl example in Markdown.

Point of sale and display settings

Pass market=ES for Spain (Spanish and EUR defaults) or market=US for the United States (English and USD). The optional language and currency parameters override these defaults. Market is an ISO 3166-1 two-letter country code; unknown codes and conflicting market/country_market values return 400.

Legacy country_market remains supported and keeps English/USD defaults. Omitting both retains US targeting and English/USD. For search by URL, explicit language/currency query parameters override values embedded in the URL; explicit URL values override market defaults.

Defaults: ES es/EUR, US en-us/USD, GB en-gb/GBP, DE de/EUR, FR fr/EUR, IT it/EUR, PT pt-pt/EUR, NL nl/EUR, IE en-gb/EUR, CA en-us/CAD, AU en-gb/AUD, JP ja/JPY. Other valid countries use en-us/USD unless overridden.

data.effective_market reports requested_country, nullable targeted_country, language, and currency. Targeting is best-effort: country_verified is false and verified_country is null because the response does not independently verify geography. A null target means country targeting was not applied. MCP returns the same object as effective_market.

{"requested_country":"ES","targeted_country":"ES","country_verified":false,"verified_country":null,"language":"es","currency":"EUR"}

For prices, total_price_value follows the displayed gross basis and is not guaranteed to include every charge. taxes_and_charges_value is the included portion (gross minus net); inspect tax_breakdown[].included for excluded taxes.

Compare the same stay, occupancy, room, rate conditions and currency. Market can change tax inclusion and displayed totals without changing the all-in price; it does not guarantee a discount or availability. In the verified Spain/US comparison, the same rate displayed US$455 including taxes in Spain and $341 excluding taxes in the US, with the same $455.46 all-in amount.

Overview

Simplest Search Method

Copy any Booking.com search URL from your browser and use it directly to get hotel results via the API.

The Search by URL endpoint allows you to use any Booking.com search results URL directly. This is perfect when you want to replicate a search you've already configured on Booking.com's website without manually extracting all the parameters.

Endpoint URL

GET https://api.stayapi.com/v1/booking/search_by_url

Query Parameters

Parameter	Type	Required	Description
url	string	Required	Booking.com search results URL to parse and execute
debug	boolean	Optional	Return parsed parameters without executing search (default: false)
country_market	string (ISO-3166)	Optional	Legacy two-letter country target (default: `US`), preserving English/USD defaults. It must match `market` if both are supplied. The echo is a request value, not verified geography.

How It Works

Step 1: Get Your URL

Go to Booking.com
Search for hotels with your desired criteria
Copy the URL from your browser's address bar

Step 2: Use the API

Pass the copied URL to this endpoint:

https://api.stayapi.com/v1/booking/search_by_url?url=https%3A%2F%2Fwww.booking.com%2Fsearchresults.html%3Fdest_id%3D-2167973%26checkin%3D2026-12-01%26checkout%3D2026-12-04...

Supported URL Parameters

The API reads these parameters from the URL:

Destination: dest_id, dest_type
Dates: checkin, checkout
Guests and rooms: group_adults, group_children, age[0], age[1], …, no_rooms. Supply one integer age 0–17 per child; missing or mismatched ages are rejected.
Paging: offset, rows
Language and currency: lang, selected_currency
Highlighted hotels: highlighted_hotels

Filters (nflt), price ranges, and sort order in the URL are not applied; results use Booking.com's default ranking. The URL must be percent-encoded when passed as the url parameter. Pass country_market as its own parameter, not inside the Booking.com URL.

Debug Mode

Testing Parameters

Use debug=true to see what parameters are extracted from your URL without running the actual search.

When debug=true, the API returns the parsed parameters instead of search results. This is useful for:

Verifying the URL is parsed correctly
Understanding what parameters are being used
Debugging search issues

Rate labels

each data.hotels[].price object includes labels (an array of readable strings), genius_discount_pct (a number or null), and is_mobile_rate (a boolean). Labels describe the quoted rate, for example Mobile rate or Bonus savings. Unlabelled rates return []. A hotel without a quoted price retains price: null.

These are anonymous public quotes. A property Genius badge alone does not prove a Genius discount on this rate. A null percentage means no rate-specific percentage was observed; is_mobile_rate: false means no explicit mobile-rate marker was observed. Labels can vary by market and occupancy and do not guarantee eligibility for logged-in member prices. Existing discount fields remain available.

Request

curl -G "https://api.stayapi.com/v1/booking/search_by_url" \
  --data-urlencode "url=https://www.booking.com/searchresults.html?dest_id=-2167973&checkin=2026-12-01&checkout=2026-12-04&group_adults=2&no_rooms=1&rows=1" \
  -H "x-api-key: YOUR_API_KEY"

const bookingUrl = "https://www.booking.com/searchresults.html?dest_id=-2167973&checkin=2026-12-01&checkout=2026-12-04&group_adults=2&no_rooms=1&rows=1";
const endpoint = "https://api.stayapi.com/v1/booking/search_by_url";
const headers = { "x-api-key": "YOUR_API_KEY" };

const response = await fetch(`${endpoint}?url=${encodeURIComponent(bookingUrl)}`, { headers });
const { data } = await response.json();
console.log(`${data.pagination.total_results} properties found`);
for (const hotel of data.hotels) {
  console.log(`${hotel.name}: ${hotel.price?.display ?? "no price"}`);
}

// Debug mode: see what was parsed from the URL without running the search
const debug = await fetch(`${endpoint}?url=${encodeURIComponent(bookingUrl)}&debug=true`, { headers });
console.log((await debug.json()).data.parsed_parameters);

import requests

booking_url = "https://www.booking.com/searchresults.html?dest_id=-2167973&checkin=2026-12-01&checkout=2026-12-04&group_adults=2&no_rooms=1&rows=1"
url = "https://api.stayapi.com/v1/booking/search_by_url"
headers = {"x-api-key": "YOUR_API_KEY"}

data = requests.get(url, headers=headers, params={"url": booking_url}).json()["data"]
print(data["pagination"]["total_results"], "properties found")
for hotel in data["hotels"]:
    price = hotel["price"] or {}
    print(hotel["name"], price.get("display"))

# Debug mode: see what was parsed from the URL without running the search
debug = requests.get(url, headers=headers, params={"url": booking_url, "debug": "true"}).json()
print(debug["data"]["parsed_parameters"])

Response

{
  "success": true,
  "url": "https://www.booking.com/searchresults.html?dest_id=-2167973&dest_type=city&group_adults=2&no_rooms=1&group_children=0&offset=0&checkin=2026-12-01&checkout=2026-12-04&lang=en-us&sb=1&src_elem=sb&aid=304142",
  "hotel_id": null,
  "data": {
    "hotels": [
      {
        "hotel_id": "16673871",
        "name": "Varandas da Bica room",
        "address": "Travessa da Laranjeira 29",
        "city": "Lisboa",
        "display_location": "Lisboa",
        "distance": "0.5 miles",
        "latitude": 38.7100533,
        "longitude": -9.1465548,
        "star_rating": null,
        "price": {
          "amount": 152.38104706769508,
          "currency": "USD",
          "display": "$152",
          "before_discount": "$277",
          "labels": [],
          "genius_discount_pct": null,
          "is_mobile_rate": false
        },
        "rating": {
          "score": 7.7,
          "review_count": 35,
          "display": "Good"
        },
        "image_url": "https://cf.bstatic.com/xdata/images/hotel/square200/886948570.jpg?k=...&o=",
        "free_cancellation": false,
        "no_prepayment": false,
        "is_sold_out": false,
        "room_name": "Economy Double Room"
      }
    ],
    "pagination": {
      "current_page": 1,
      "per_page": 1,
      "total_results": 5036,
      "total_pages": 1001,
      "has_next_page": true,
      "has_previous_page": false,
      "offset": 0
    },
    "hotels_found": 1,
    "search_url": "https://www.booking.com/searchresults.html?dest_id=-2167973&dest_type=city&group_adults=2&no_rooms=1&group_children=0&offset=0&checkin=2026-12-01&checkout=2026-12-04&lang=en-us&sb=1&src_elem=sb&aid=304142",
    "metadata": {
      "dest_id": -2167973,
      "dest_type": "CITY",
      "checkin": "2026-12-01",
      "checkout": "2026-12-04",
      "adults": 2,
      "children": 0,
      "rooms": 1,
      "children_ages": [],
      "highlighted_hotels": [],
      "rows_per_page": 1,
      "offset": 0,
      "travel_purpose": 2,
      "language": "en-us",
      "currency": "USD",
      "country_market": "US",
      "original_browser_url": "https://www.booking.com/searchresults.html?dest_id=-2167973&checkin=2026-12-01&checkout=2026-12-04&group_adults=2&no_rooms=1&rows=1",
      "parsed_parameters": {
        "dest_id": -2167973,
        "dest_type": "CITY",
        "checkin": "2026-12-01",
        "checkout": "2026-12-04",
        "adults": 2,
        "children": 0,
        "rooms": 1,
        "offset": 0,
        "rows_per_page": 1,
        "language": "en-us",
        "currency": "USD",
        "travel_purpose": 2,
        "original_url": "https://www.booking.com/searchresults.html?dest_id=-2167973&checkin=2026-12-01&checkout=2026-12-04&group_adults=2&no_rooms=1&rows=1",
        "parsed_successfully": true
      },
      "url_parsed_at": "2026-09-24T17:07:49.037434Z"
    }
  },
  "message": "URL-based search successful. Found 1 hotels",
  "retrieved_at": "2026-09-24T17:07:49.035426Z"
}

{
  "success": true,
  "url": "https://www.booking.com/searchresults.html?dest_id=-2167973&checkin=2026-12-01&checkout=2026-12-04&group_adults=2&no_rooms=1&rows=1",
  "hotel_id": null,
  "data": {
    "parsed_parameters": {
      "dest_id": -2167973,
      "dest_type": "CITY",
      "checkin": "2026-12-01",
      "checkout": "2026-12-04",
      "adults": 2,
      "children": 0,
      "rooms": 1,
      "offset": 0,
      "rows_per_page": 1,
      "language": "en-us",
      "currency": "USD",
      "travel_purpose": 2,
      "original_url": "https://www.booking.com/searchresults.html?dest_id=-2167973&checkin=2026-12-01&checkout=2026-12-04&group_adults=2&no_rooms=1&rows=1",
      "parsed_successfully": true
    },
    "original_url": "https://www.booking.com/searchresults.html?dest_id=-2167973&checkin=2026-12-01&checkout=2026-12-04&group_adults=2&no_rooms=1&rows=1",
    "note": "Debug mode - parameters extracted but search not executed"
  },
  "message": "Debug mode - URL parsed successfully",
  "retrieved_at": "2026-09-24T17:07:49.222055Z"
}

{
  "errors": [
    {
      "type": "missing",
      "loc": [
        "query",
        "url"
      ],
      "msg": "Field required",
      "input": null,
      "url": "https://errors.pydantic.dev/2.13/v/missing"
    }
  ],
  "error": "Validation Error",
  "status_code": 422,
  "type": "https://api.stayapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "Request validation failed",
  "error_code": "VALIDATION_ERROR",
  "instance": "/v1/booking/search_by_url",
  "provider": "booking",
  "correlation_id": "0a8629d8-dc65-48f2-9de6-912dd31ce5d9"
}