# Agoda search: `POST /v1/ota/agoda/search`

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

Resolve a hotel name to Agoda's numeric property identifier.

No partner credentials are needed. Add `city` to disambiguate common
brands,
then store `recommended_match.property_id` for room and rate-plan 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. Included in Agoda's query and used to rank same-brand results in the intended city.
- `origin` (string; optional; default US; 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; min length 2, max length 2): Two-letter user-country context sent to Agoda. This is not the hotel's country; `city` identifies the location.
- `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 agoda_search)
  - `search_parameters.name` (string; required)
  - `search_parameters.city` (string; required)
  - `search_parameters.origin` (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 Agoda id; pass as `property_id`.
  - `recommended_match.name` (string; required)
  - `recommended_match.city` (string; required)
  - `recommended_match.country` (string; required)
  - `recommended_match.location` (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.city_score` (number; optional): Present only when `city` was supplied.
- `warnings` (array of string; required)
- `matches` (array of object; required): Candidates, best first, for manual review.
  - `matches[].property_id` (string; required): Numeric Agoda id; pass as `property_id`.
  - `matches[].name` (string; required)
  - `matches[].city` (string; required)
  - `matches[].country` (string; required)
  - `matches[].location` (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[].city_score` (number; optional): Present only when `city` was supplied.
- `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)
