Agoda search

Request#

Authenticate with your API key in the x-api-key header (see Authentication).

Body#

JSON object. Unknown fields are rejected with 422.

• namestringrequiredmin length 1

  Hotel name as a guest would search for it.

• citystringdefault

  Strongly recommended. Included in Agoda's query and used to rank same-brand results in the intended city.

• originstringdefault USmin length 2, max length 2

  Two-letter user-country context sent to Agoda. This is not the hotel's country; city identifies the location.

  251 allowed values

  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

• limitintegerdefault 5min 1, max 10

  Maximum hotel candidates to return, best match first.

Example request#

curl -X POST "https://api.scrapercompany.com/v1/ota/agoda/search" \
  -H "x-api-key: $SCRAPERCOMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Moxy Boston Downtown",
    "city": "Boston"
  }'

Response#

200 — Candidate Agoda numeric property ids, with city-aware ranking. Metered responses carry x-credits-charged and x-credits-remaining headers (see credit headers).

{
  "search_parameters": {
    "engine": "agoda_search",
    "name": "Moxy Boston Downtown",
    "city": "Boston",
    "origin": "US",
    "limit": 5
  },
  "search_status": "matched",
  "recommended_match": {
    "property_id": "8795952",
    "name": "Moxy Boston Downtown",
    "city": "Boston (MA)",
    "country": "US",
    "location": "Boston (MA), United States",
    "rank": 0,
    "score": 1,
    "name_score": 1,
    "identity_score": 1,
    "match_score": 1,
    "confidence": "high",
    "city_score": 1
  },
  "warnings": [],
  "matches": [
    {
      "property_id": "8795952",
      "name": "Moxy Boston Downtown",
      "city": "Boston (MA)",
      "country": "US",
      "location": "Boston (MA), United States",
      "rank": 0,
      "score": 1,
      "name_score": 1,
      "identity_score": 1,
      "match_score": 1,
      "confidence": "high",
      "city_score": 1
    }
  ],
  "meta": {
    "source": "agoda",
    "matches": 1,
    "selection_method": "name_city_confidence",
    "match_threshold": 0.8,
    "match_margin": 0.12,
    "wire_bytes": 8144,
    "elapsed_s": 0.221
  }
}

Response fields#

Fields marked required are always present; others appear when they apply.

• search_parametersobjectrequired
  Show 5 child fieldsHide child fields

  • search_parameters.enginestringrequired

    One ofagoda_search

  • search_parameters.namestringrequired
  • search_parameters.citystringrequired
  • search_parameters.originstringrequired
  • search_parameters.limitintegerrequired
• search_statusstringrequired

  matched only when the top candidate clears the identity threshold and margin.

  One ofmatchedambiguousnot_found

• recommended_matchobject | nullrequired

  Safe to store; null unless search_status is matched.

  Show 12 child fieldsHide child fields

  • recommended_match.property_idstringrequired

    Numeric Agoda id; pass as property_id.

  • recommended_match.namestringrequired
  • recommended_match.citystringrequired
  • recommended_match.countrystringrequired
  • recommended_match.locationstringrequired
  • recommended_match.rankintegerrequired
  • recommended_match.scorenumberrequired
  • recommended_match.name_scorenumberrequired
  • recommended_match.identity_scorenumberrequired
  • recommended_match.match_scorenumberrequired
  • recommended_match.confidencestringrequired

    One ofhighmediumlow

  • recommended_match.city_scorenumber

    Present only when city was supplied.

• warningsarray of stringrequired
• matchesarray of objectrequired

  Candidates, best first, for manual review.

  Show 12 child fieldsHide child fields

  • matches[].property_idstringrequired

    Numeric Agoda id; pass as property_id.

  • matches[].namestringrequired
  • matches[].citystringrequired
  • matches[].countrystringrequired
  • matches[].locationstringrequired
  • matches[].rankintegerrequired
  • matches[].scorenumberrequired
  • matches[].name_scorenumberrequired
  • matches[].identity_scorenumberrequired
  • matches[].match_scorenumberrequired
  • matches[].confidencestringrequired

    One ofhighmediumlow

  • matches[].city_scorenumber

    Present only when city was supplied.

• metaobjectrequired
  Show 7 child fieldsHide child fields

  • meta.sourcestringrequired
  • meta.matchesintegerrequired
  • meta.selection_methodstringrequired
  • meta.match_thresholdnumberrequired
  • meta.match_marginnumberrequired
  • meta.wire_bytesintegerrequired
  • meta.elapsed_snumberrequired

Errors#

Errors return a JSON body with a detail field. Failed requests are not charged. See Errors for the full list and retry advice.

Try it#

1. Export your key: export SCRAPERCOMPANY_API_KEY=sk_... (no key yet? request access).
2. Copy the cURL example above and run it in a terminal.
3. Or open the interactive playground on api.scrapercompany.com, paste your key and pick this endpoint.