Search properties

Request#

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

Body#

JSON object. Unknown fields are rejected with 422.

• namestringrequired

  Property name as a guest would type it. Fuzzy — exact punctuation does not matter.

• citystringdefault

  Strongly recommended. Without it a common brand name matches the wrong city.

• marketstring | null

  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.

  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

• fallback_marketsarray of stringdefault ["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.

• currencystring | null

  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.

  39 allowed values

  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

• limitintegerdefault 5min 1, max 10

  Candidates to return, best match first.

• verifybooleandefault true

  Fetch each candidate to confirm the token resolves and read back its real name. Slower, far fewer wrong matches.

Example request#

curl -X POST "https://api.scrapercompany.com/v1/search" \
  -H "x-api-key: $SCRAPERCOMPANY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hilton Chicago",
    "city": "Chicago",
    "market": "US"
  }'

Response#

200 — Candidate properties, best match first. Metered responses carry x-credits-charged and x-credits-remaining headers (see credit headers).

{
  "query": "Blue Horizons Garden Resort St George's",
  "gl": "us",
  "requested_market": "GD",
  "attempted_markets": [
    "GD",
    "US"
  ],
  "matched_market": "US",
  "market_fallback_used": true,
  "search_status": "matched",
  "external_fallback_recommended": false,
  "matches": [
    {
      "token": "ChcI7LnnsZLasKYOGgsvZy8xdHJzejFiORAB",
      "rank": 0,
      "verified": true,
      "name": "Blue Horizons Garden Resort",
      "name_score": 1
    }
  ]
}

Response fields#

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

• querystringrequired

  name and city as searched.

• glstringrequired

  Google country (gl) of the market that matched, or of the first market tried.

• requested_marketstringrequired
• attempted_marketsarray of stringrequired

  Markets tried, in order, up to and including the one that matched.

• matched_marketstring | nullrequired
• market_fallback_usedbooleanrequired
• search_statusstringrequired

  One ofmatchednot_found

• external_fallback_recommendedbooleanrequired

  True when nothing matched.

• matchesarray of objectrequired

  Best match first when verify is on (verified, then name score, then Google rank).

  Show 5 child fieldsHide child fields

  • matches[].tokenstringrequired

    Google property token; pass it as token / property_token.

  • matches[].rankintegerrequired

    Google's own ordering, 0 = first.

  • matches[].verifiedboolean | nullrequired

    Whether the token prices. null when verify was false.

  • matches[].namestring | nullrequired

    Property name read back from Google. null when unchecked, empty string when checked but unreadable.

  • matches[].name_scorenumber | nullrequired

    0-1 word-overlap between the requested and real name. null when unchecked.

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.