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 properties from the first page of results, one row per property card. Provide a destination and optional stay dates; the operation builds the search URL and extracts data from the English-language site.

When to use it. Use this to retrieve current availability, pricing, and review scores for a location without managing Booking.com sessions or parsing HTML yourself. Use checkin and checkout when you need priced results; omit them for a lighter unpriced preview. Use country and city when you need results as seen from a specific geography, and premium if standard proxies are blocked.

Dates are coupled: checkin and checkout are both required if either is supplied; one without the other returns 422.
Empty results are still charged: a search that finds no properties returns 200 with hotels: [] and status: done, consuming 30 credits.
Field presence varies: any field absent from a property card is omitted from its row; do not expect a fixed schema across results.

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 instead of the standard one. Free here, unlike on `/crawl` -- the price is flat -- but worth trying if the standard pool is being turned away. `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=&currency=&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
}

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.

← GET /screenshot Full reference GET /booking/hotel →

Start building with Irmu today

200 free credits every month, no card required. Every API, every integration, one key.

Start free Read the docs