API Reference
Search Booking.com
GET /booking/search — bearer auth, JSON responses, billed per successful request.
GET/booking/search
Search Booking.com
Searches Booking.com for accommodations and returns the first page of property results, with one row per property card. Results are always scraped from the English-language site.
When to use it: Use this endpoint when you need structured property listings from Booking.com for a specific destination, with optional date and guest filtering. Prefer this over /crawl when you only need the first page of results and want a flat 30-credit cost regardless of proxy routing choices. Use the key query parameter or Authorization header for authentication.
checkinandcheckoutare interdependent: providing one without the other returns422- Empty result sets still cost 30 credits and return
200withstatus: doneand an emptyhotelsarray premiumdefaults totrue; explicitly sendfalseto use the standard proxy pool, though this typically results in blocks from Booking.com
| Parameter | In | Type | Description |
|---|---|---|---|
| destination * | query | string | Where to stay, as you would type it into Booking's search box -- a city, a region, a landmark. Up to 200 characters. |
| checkin | query | string<date> | The first night, as `YYYY-MM-DD`, today or later. **Requires `checkout`.** Optional: without dates Booking still shows the page, it just prices nothing. |
| checkout | query | string<date> | The day you leave, as `YYYY-MM-DD`, after `checkin`. **Requires `checkin`.** |
| adults | query | integer | How many adults are staying. |
| rooms | query | integer | How many rooms they need. |
| currency | query | string | The currency to price in, as a three-letter ISO 4217 code. Left to Booking when absent, which usually means the currency of the country the crawl exits from. |
| premium | query | string | Go through the premium proxy pool rather than the standard one. **On by default**, because the standard pool is the one Booking turns away; send `false` to use the standard pool. Free either way, unlike on `/crawl` -- the price is flat. `true`, `false`, `1`, `0`, `yes`, `no`, `on`, `off`, in any case. Anything else is refused rather than read as `false`. |
| country | query | string | The country to appear to be browsing from, as a two-letter ISO 3166-1 alpha-2 code. Free. Booking prices and ranks by where you are, so this can change the answer. Required to use `city`. |
| city | query | string | The city inside that country, as the pool spells it. **Requires `country`.** Free here, where on `/crawl` it doubles the price. |
| key | query | string | The API key, as an alternative to the `Authorization` header. Ignored when a header is present. |
request.sh
curl -X GET "https://app.irmu.com/api/booking/search?destination=&checkin=&checkout=&adults=&rooms=¤cy=&premium=&country=&city=&key=" \
-H "Authorization: Bearer $IRMU_API_KEY"200.json
{
"url": "https://www.booking.com/searchresults.en-gb.html?ss=Rome&checkin=2026-11-11&checkout=2026-11-12&group_adults=2&no_rooms=1&group_children=0",
"destination": "Rome",
"checkin": "2026-11-11",
"checkout": "2026-11-12",
"adults": 2,
"rooms": 1,
"currency": null,
"hotels": [
{
"name": "Hotel Artemide",
"url": "https://www.booking.com/hotel/it/artemide.en-gb.html",
"image": "https://cf.bstatic.com/xdata/images/hotel/square240/1.jpg",
"price": "€ 212",
"priceInfo": "1 night, 2 adults",
"taxes": "+€ 12 taxes and charges",
"address": "Termini, Rome",
"distance": "1.2 km from centre",
"reviewScore": "9.1",
"reviewWord": "Wonderful",
"reviewCount": "3,214 reviews",
"stars": "4 out of 5 Property rating"
}
],
"credits_charged": 30,
"credits_remaining": 970,
"job_id": "0198a9b6-1f4c-7c3e-9a2b-5d8e6f0a1b23_0198a9b6-2a71-7f0d-8c44-9e1b3c5d7f02",
"status": "done",
"position": null,
"debug": null,
"error": null
}Guides using this endpoint
- How to Give Claude, ChatGPT and Cursor Live Web Access with an MCP Server
- Booking.com API Alternative: Get Hotel Data Without Partner Approval
- How to Scrape Hotel Prices and Build a Hotel Database (2026)
request.js
const res = await fetch("https://app.irmu.com/api/booking/search", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.IRMU_API_KEY}`,
"Content-Type": "application/json",
}
});
const data = await res.json();request.py
import os, requests
res = requests.get(
"https://app.irmu.com/api/booking/search",
headers={"Authorization": f"Bearer {os.environ['IRMU_API_KEY']}"}
)
print(res.json())| Status | Meaning |
|---|---|
| 200 | The properties the search found. |
| 202 | Paid for and still going. Collect it from `/crawl/{job}`, free, as a slow crawl is collected. That endpoint answers the crawl envelope, so what is lifted into `hotels` here arrives under `data` there. |
| 401 | No key, an unknown key, or a caller that is not an organization. |
| 402 | Not enough credits, or the daily limit is reached. Nothing is charged and no attempt is recorded. |
| 422 | A malformed request -- no destination, one date without the other, dates in the past, or a flag that is not a yes or a no. |
| 500 | The crawl failed outright. A search that ran and found nothing is not this: it is a `200` with an empty `hotels`. **The credits are refunded**, so `credits_charged` is `0`. The attempt is still recorded against `www.booking.com`. |
| 503 | The crawl could not be routed through a proxy pool. Nothing is charged. |
Start building with Irmu today
200 free credits every month, no card required. Every API, every integration, one key.