GET # Search by URL API Search for hotels using a Booking.com search results URL directly from your browser. ## 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 1. Go to Booking.com 2. Search for hotels with your desired criteria 3. 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 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" ``` Response ```json { "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" } ``` ```json { "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" } ```