# Search properties: `POST /v1/search`

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

Resolve a hotel name to candidate property tokens.

Verification is on by default: each candidate is checked with a calendar lookup (slower, but no extra credits; a search costs 2 credits).
That is the right default for onboarding: a wrong token yields rates that
are entirely plausible and belong to a different hotel. Turn it off only
when a human is going to confirm the choice anyway.

Not a hot path — tokens are stable, so resolve once and store the result.
Google rate-limits this more aggressively than the calendar.

Request body (JSON):

- `name` (string; required): Property name as a guest would type it. Fuzzy — exact punctuation does not matter.
- `city` (string; optional; default ): Strongly recommended. Without it a common brand name matches the wrong city.
- `market` (string | null; optional; one of AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UK, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, XK, YE, YT, ZA, ZM, ZW): ISO country/Google market to try first, e.g. `US`, `MX`, `GD`. Search accepts markets beyond the pricing markets listed by `GET /v1/markets` because property tokens are global; the response reports where it matched.
- `fallback_markets` (array of string; optional; default ["US"]; max items 5): Markets tried in order only when the requested market returns zero candidates. Defaults to `US`, which often indexes Caribbean properties absent from their local Google market. Pass `[]` to disable fallback. The response always reports `attempted_markets`, `matched_market`, and `market_fallback_used`.
- `currency` (string | null; optional; one of AED, ARS, AUD, BRL, CAD, CHF, CLP, CNY, COP, CZK, DKK, EGP, EUR, GBP, HKD, HUF, IDR, ILS, INR, JPY, KRW, MXN, MYR, NOK, NZD, PEN, PHP, PLN, QAR, RON, SAR, SEK, SGD, THB, TRY, TWD, USD, VND, ZAR): ISO 4217 code for the returned prices. Major currencies include AED, AUD, BRL, CAD, CHF, CNY, EUR, GBP, HKD, INR, JPY, KRW, MXN, NZD, SGD, USD; all 39 supported codes are listed in the enum.
- `limit` (integer; optional; default 5; min 1, max 10): Candidates to return, best match first.
- `verify` (boolean; optional; default true): Fetch each candidate to confirm the token resolves and read back its real name. Slower, far fewer wrong matches.

Response fields:

- `query` (string; required): `name` and `city` as searched.
- `gl` (string; required): Google country (`gl`) of the market that matched, or of the first market tried.
- `requested_market` (string; required)
- `attempted_markets` (array of string; required): Markets tried, in order, up to and including the one that matched.
- `matched_market` (string | null; required)
- `market_fallback_used` (boolean; required)
- `search_status` (string; required; one of matched, not_found)
- `external_fallback_recommended` (boolean; required): True when nothing matched.
- `matches` (array of object; required): Best match first when `verify` is on (verified, then name score, then Google rank).
  - `matches[].token` (string; required): Google property token; pass it as `token` / `property_token`.
  - `matches[].rank` (integer; required): Google's own ordering, 0 = first.
  - `matches[].verified` (boolean | null; required): Whether the token prices. `null` when `verify` was false.
  - `matches[].name` (string | null; required): Property name read back from Google. `null` when unchecked, empty string when checked but unreadable.
  - `matches[].name_score` (number | null; required): 0-1 word-overlap between the requested and real name. `null` when unchecked.

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)
