Booking.com 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 for common hotel names. It is sent to Booking.com with the name so results come from the intended city.

• limitintegerdefault 5min 1, max 10

  Maximum candidates to return, best match first.

Example request#

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

Response#

200 — Candidate Booking.com URL slugs, ranked against the requested hotel name. Metered responses carry x-credits-charged and x-credits-remaining headers (see credit headers).

{
  "search_parameters": {
    "engine": "booking_search",
    "name": "Moxy Boston Downtown",
    "city": "Boston",
    "limit": 5
  },
  "search_status": "matched",
  "recommended_match": {
    "pagename": "moxy-boston-downtown",
    "country": "us",
    "name": "Moxy Boston Downtown",
    "url": "https://www.booking.com/hotel/us/moxy-boston-downtown.html",
    "rank": 0,
    "name_score": 1,
    "identity_score": 1,
    "match_score": 1,
    "confidence": "high"
  },
  "warnings": [],
  "matches": [
    {
      "pagename": "moxy-boston-downtown",
      "country": "us",
      "name": "Moxy Boston Downtown",
      "url": "https://www.booking.com/hotel/us/moxy-boston-downtown.html",
      "rank": 0,
      "name_score": 1,
      "identity_score": 1,
      "match_score": 1,
      "confidence": "high"
    }
  ],
  "meta": {
    "source": "booking",
    "matches": 1,
    "selection_method": "name_city_confidence",
    "match_threshold": 0.8,
    "match_margin": 0.12,
    "wire_bytes": 1384521,
    "elapsed_s": 1.214
  }
}

Response fields#

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

• search_parametersobjectrequired
  Show 4 child fieldsHide child fields

  • search_parameters.enginestringrequired

    One ofbooking_search

  • search_parameters.namestringrequired
  • search_parameters.citystringrequired
  • 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 9 child fieldsHide child fields

  • recommended_match.pagenamestringrequired

    URL slug; pass as pagename.

  • recommended_match.countrystringrequired

    Two-letter URL segment; pass as country.

  • recommended_match.namestringrequired
  • recommended_match.urlstringrequired
  • recommended_match.rankintegerrequired
  • recommended_match.name_scorenumberrequired
  • recommended_match.identity_scorenumberrequired
  • recommended_match.match_scorenumberrequired
  • recommended_match.confidencestringrequired

    One ofhighmediumlow

• warningsarray of stringrequired
• matchesarray of objectrequired

  Candidates, best first, for manual review.

  Show 9 child fieldsHide child fields

  • matches[].pagenamestringrequired

    URL slug; pass as pagename.

  • matches[].countrystringrequired

    Two-letter URL segment; pass as country.

  • matches[].namestringrequired
  • matches[].urlstringrequired
  • matches[].rankintegerrequired
  • matches[].name_scorenumberrequired
  • matches[].identity_scorenumberrequired
  • matches[].match_scorenumberrequired
  • matches[].confidencestringrequired

    One ofhighmediumlow

• 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.