# Hotels.com search: `POST /v1/ota/hotels/search`

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

Resolve a hotel name to Hotels.com's numeric property identifier.

Add `city` to disambiguate common brands,
then store `recommended_match.property_id` for headline-price and room
calls. It is null when only weak or ambiguous candidates were found.

Request body (JSON):

- `name` (string; required; min length 1): Hotel name as a guest would search for it.
- `city` (string; optional; default ): Strongly recommended. Used both in Hotels.com's query and in local candidate ranking so same-brand hotels in other cities rank lower.
- `market` (string; optional; default US; one of AU, CA, DE, EU, FR, GB, IE, IT, NL, NZ, US): Hotels.com point-of-sale used for search results. This also matches the market accepted by the rate and room endpoints.
- `limit` (integer; optional; default 5; min 1, max 10): Maximum hotel candidates to return, best match first.

Response fields:

- `search_parameters` (object; required)
  - `search_parameters.engine` (string; required; one of hotels_search)
  - `search_parameters.name` (string; required)
  - `search_parameters.city` (string; required)
  - `search_parameters.market` (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.property_id` (string; required): Numeric Hotels.com id (digits); pass as `property_id`.
  - `recommended_match.name` (string; required)
  - `recommended_match.city` (string; required)
  - `recommended_match.address` (string; required)
  - `recommended_match.country` (string; required)
  - `recommended_match.url` (string; required)
  - `recommended_match.rank` (integer; required)
  - `recommended_match.score` (number; 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)
  - `recommended_match.winner_reason` (string; required)
  - `recommended_match.city_score` (number; optional): Present only when `city` was supplied.
  - `recommended_match.coordinates` (object; optional): Present only when the source returned coordinates.
- `warnings` (array of string; required)
- `matches` (array of object; required): Candidates, best first, for manual review.
  - `matches[].property_id` (string; required): Numeric Hotels.com id (digits); pass as `property_id`.
  - `matches[].name` (string; required)
  - `matches[].city` (string; required)
  - `matches[].address` (string; required)
  - `matches[].country` (string; required)
  - `matches[].url` (string; required)
  - `matches[].rank` (integer; required)
  - `matches[].score` (number; 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)
  - `matches[].winner_reason` (string; required)
  - `matches[].city_score` (number; optional): Present only when `city` was supplied.
  - `matches[].coordinates` (object; optional): Present only when the source returned coordinates.
- `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)
