GET

Search by URL API

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

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	Two-letter market country (default: `US`). Booking.com prices by the visitor's country, so the same stay can cost different amounts per market. Use the same value across search, rooms, and prices for matching numbers; the value used is echoed in the response.

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
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

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"
        },
        "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",
      "scraped_at": "2026-09-24T17:07:49.035426Z",
      "api_method": "mobile_graphql",
      "diagnostics": {
        "upstream_results_count": 1,
        "parsed_hotels_count": 1,
        "invalid_hotel_id_count": 0,
        "invalid_hotel_id_examples": []
      },
      "source_method": "url_parsing",
      "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 using URL-based search",
  "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",
    "method": "url_parsing_debug",
    "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"
}