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

  • checkin and checkout are interdependent: providing one without the other returns 422
  • Empty result sets still cost 30 credits and return 200 with status: done and an empty hotels array
  • premium defaults to true; explicitly send false to use the standard proxy pool, though this typically results in blocks from Booking.com
ParameterInTypeDescription
destination *querystringWhere to stay, as you would type it into Booking's search box -- a city, a region, a landmark. Up to 200 characters.
checkinquerystring<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.
checkoutquerystring<date>The day you leave, as `YYYY-MM-DD`, after `checkin`. **Requires `checkin`.**
adultsqueryintegerHow many adults are staying.
roomsqueryintegerHow many rooms they need.
currencyquerystringThe 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.
premiumquerystringGo 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`.
countryquerystringThe 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`.
cityquerystringThe city inside that country, as the pool spells it. **Requires `country`.** Free here, where on `/crawl` it doubles the price.
keyquerystringThe 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())
StatusMeaning
200The properties the search found.
202Paid 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.
401No key, an unknown key, or a caller that is not an organization.
402Not enough credits, or the daily limit is reached. Nothing is charged and no attempt is recorded.
422A malformed request -- no destination, one date without the other, dates in the past, or a flag that is not a yes or a no.
500The 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`.
503The 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.