Hotels.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. Used both in Hotels.com's query and in local candidate ranking so same-brand hotels in other cities rank lower.

• marketstringdefault US

  Hotels.com point-of-sale used for search results. This also matches the market accepted by the rate and room endpoints.

  One ofAUCADEEUFRGBIEITNLNZUS

• limitintegerdefault 5min 1, max 10

  Maximum hotel candidates to return, best match first.

Example request#

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

Response#

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

{
  "search_parameters": {
    "engine": "hotels_search",
    "name": "Moxy Boston Downtown",
    "city": "Boston",
    "market": "US",
    "limit": 5
  },
  "search_status": "matched",
  "recommended_match": {
    "property_id": "38766175",
    "name": "Moxy Boston Downtown",
    "city": "Boston",
    "address": "240 TREMONT STREET, Boston, MA",
    "country": "USA",
    "url": "https://www.hotels.com/ho38766175",
    "rank": 0,
    "score": 1,
    "name_score": 1,
    "identity_score": 1,
    "match_score": 1,
    "confidence": "high",
    "city_score": 1,
    "winner_reason": "EXACT_MATCH",
    "coordinates": {
      "latitude": 42.350952,
      "longitude": -71.064804
    }
  },
  "warnings": [],
  "matches": [
    {
      "property_id": "38766175",
      "name": "Moxy Boston Downtown",
      "city": "Boston",
      "address": "240 TREMONT STREET, Boston, MA",
      "country": "USA",
      "url": "https://www.hotels.com/ho38766175",
      "rank": 0,
      "score": 1,
      "name_score": 1,
      "identity_score": 1,
      "match_score": 1,
      "confidence": "high",
      "city_score": 1,
      "winner_reason": "EXACT_MATCH",
      "coordinates": {
        "latitude": 42.350952,
        "longitude": -71.064804
      }
    }
  ],
  "meta": {
    "source": "hotels",
    "matches": 1,
    "selection_method": "name_city_confidence",
    "match_threshold": 0.8,
    "match_margin": 0.12,
    "wire_bytes": 921,
    "elapsed_s": 0.184
  }
}

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 ofhotels_search

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

  • recommended_match.property_idstringrequired

    Numeric Hotels.com id (digits); pass as property_id.

  • recommended_match.namestringrequired
  • recommended_match.citystringrequired
  • recommended_match.addressstringrequired
  • recommended_match.countrystringrequired
  • recommended_match.urlstringrequired
  • 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.winner_reasonstringrequired
  • recommended_match.city_scorenumber

    Present only when city was supplied.

  • recommended_match.coordinatesobject

    Present only when the source returned coordinates.

    Show 2 child fieldsHide child fields

    • recommended_match.coordinates.latitudenumberrequired
    • recommended_match.coordinates.longitudenumberrequired
• warningsarray of stringrequired
• matchesarray of objectrequired

  Candidates, best first, for manual review.

  Show 15 child fieldsHide child fields

  • matches[].property_idstringrequired

    Numeric Hotels.com id (digits); pass as property_id.

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

    One ofhighmediumlow

  • matches[].winner_reasonstringrequired
  • matches[].city_scorenumber

    Present only when city was supplied.

  • matches[].coordinatesobject

    Present only when the source returned coordinates.

    Show 2 child fieldsHide child fields

    • matches[].coordinates.latitudenumberrequired
    • matches[].coordinates.longitudenumberrequired
• 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.