# Booking.com search: `POST /v1/ota/booking/search`

Cost: 4 credits (4 (failed requests are free)). Docs: https://scrapercompany.com/docs/reference/booking-search

Resolve a hotel name to Booking.com's country/slug identifier.

Add `city` whenever possible. A slug is stable, so search once during
onboarding and store `recommended_match` for calendar and room calls.
It is null when only weak or ambiguous candidates were found; `matches`
remains available for manual review.
A deployment without Booking support answers HTTP 501, like the rate
endpoints.

Request body (JSON):

- `name` (string; required; min length 1): Hotel name as a guest would search for it.
- `city` (string; optional; default ): Strongly recommended for common hotel names. It is sent to Booking.com with the name so results come from the intended city.
- `limit` (integer; optional; default 5; min 1, max 10): Maximum candidates to return, best match first.

Response fields:

- `search_parameters` (object; required)
  - `search_parameters.engine` (string; required; one of booking_search)
  - `search_parameters.name` (string; required)
  - `search_parameters.city` (string; required)
  - `search_parameters.limit` (integer; required)
- `search_status` (string; required; one of matched, ambiguous, not_found): `matched` only when the top candidate clears the identity threshold and margin.
- `recommended_match` (object | null; required): Safe to store; null unless `search_status` is `matched`.
  - `recommended_match.pagename` (string; required): URL slug; pass as `pagename`.
  - `recommended_match.country` (string; required): Two-letter URL segment; pass as `country`.
  - `recommended_match.name` (string; required)
  - `recommended_match.url` (string; required)
  - `recommended_match.rank` (integer; required)
  - `recommended_match.name_score` (number; required)
  - `recommended_match.identity_score` (number; required)
  - `recommended_match.match_score` (number; required)
  - `recommended_match.confidence` (string; required; one of high, medium, low)
- `warnings` (array of string; required)
- `matches` (array of object; required): Candidates, best first, for manual review.
  - `matches[].pagename` (string; required): URL slug; pass as `pagename`.
  - `matches[].country` (string; required): Two-letter URL segment; pass as `country`.
  - `matches[].name` (string; required)
  - `matches[].url` (string; required)
  - `matches[].rank` (integer; required)
  - `matches[].name_score` (number; required)
  - `matches[].identity_score` (number; required)
  - `matches[].match_score` (number; required)
  - `matches[].confidence` (string; required; one of high, medium, low)
- `meta` (object; required)
  - `meta.source` (string; required)
  - `meta.matches` (integer; required)
  - `meta.selection_method` (string; required)
  - `meta.match_threshold` (number; required)
  - `meta.match_margin` (number; required)
  - `meta.elapsed_s` (number; required)

Base URL: `https://api.scrapercompany.com`. Auth: send your key in the `x-api-key` header. A failed request (4xx or 5xx) or an empty result costs 0 credits.

- [Full API reference as one Markdown file](https://scrapercompany.com/llms-full.txt)
- [OpenAPI spec](https://scrapercompany.com/openapi.json)
