Find Match API solutions

The Find Match API takes a single hotel record you hold (name, address, coordinates and, if available, phone and website) and finds its counterpart in the hotelmapping.org database. The response returns the matching HM ID, a 0 to 1 confidence score and the decision made from that score. It also works for records that have no supplier code.

What you gain

  • No supplier code needed

    For your contracted hotels, extranet records or a free-text hotel name, name and location information is enough.

  • Score and decision together

    Every response returns a confidence score and a decision field. You can also restrict which records to accept automatically with your own business rules.

  • Resilient to spelling differences

    Abbreviations, missing suffixes, and Cyrillic and Arabic script names go through normalization. Differences such as "Rsrt." and "Resort" are compared at the character and word level in name similarity.

  • Candidate list

    The most likely candidates come back with their distances and scores, making it easier to decide on records that need review.

Before and after

A record with no supplier code, from the agency's own system

contracted_hotels.csv
internal_id,name,city,lat,lng,phone
K-0192,Отель Лара Палм,Анталья,36.8567,30.7969,0242 000 00 00

Find Match API result

POST /v1/match → 200 OK
{
  "reference": "K-0192",
  "normalized_name": "lara palm",
  "decision": "auto_match",
  "hm_id": "HM-1052207",
  "name": "Lara Palm Hotel",
  "confidence": 0.973,
  "signals": {
    "name_similarity": 0.95,
    "distance_m": 63,
    "phone_match": true
  }
}

Sample data; the hotel name, phone and codes do not belong to a real property. The Russian name is transliterated to Latin script and the "hotel" suffix is split off before comparison.

How it works

  1. 1

    Request

    The hotel name and location information are sent to the POST /v1/match endpoint. The match gets stronger as you add coordinates, address, phone and website.

  2. 2

    Normalization

    Suffixes such as "Hotel", "Resort & Spa" and "Otel" are split off the name; Russian and Arabic names are transliterated to Latin script; the phone number is reduced to international format and the website to its domain.

  3. 3

    Candidate search

    The record is compared only with nearby hotels: a geographic cell of about 500 meters, name similarity, and the same phone number or domain.

  4. 4

    Scoring

    Name similarity, multilingual embedding similarity, distance, phone and website matches, star rating and postal code combine into a probability score between 0 and 1.

  5. 5

    Decision

    A score of 0.97 or higher returns auto_match, between 0.80 and 0.97 returns review, and below 0.80 returns no_match; in a no_match response, hm_id is null. The response also includes the most likely candidates.

When is the Find Match API used?

The hotel mapping product links supplier files to HM IDs in bulk. The Find Match API, on the other hand, is for querying a single record instantly. Typical use cases:

  • Linking your contracted hotels or extranet records one by one to an HM ID. Bulk contracted-hotel mapping through the portal is planned.
  • Trying sample records before you start working with a new supplier.
  • Converting free-text hotel names in a booking, CRM or accounting system into a standard identifier.
  • Linking a hotel name typed into a search box or an AI assistant, together with location information, to the correct property.

We explain the general logic of mapping in the hotel mapping guide.

The decision field in the response

Confidence score decision What to do
0.97 and above auto_match You can use the HM ID directly
0.80 to 0.97 review Check the candidates; look at differences in name, distance and phone
Below 0.80 no_match hm_id returns null. The property may not be in the database yet; check the name and location

Thresholds are tuned against a manually labeled test set and may change between releases. We explain which signals make up the score under the match score term.

For better results

  • Send coordinates. Candidate search starts with a geographic cell. Without coordinates, city and address are used; the number of candidates rises and the score is generally lower. You can find how an address is converted to coordinates under the geocoding term.
  • Add phone and website. The same phone number or domain is a strong match signal.
  • Send the name as is. Cyrillic or Arabic script names are converted to Latin script through transliteration.
  • Use the reference field. Your own record ID returns in the response unchanged, making it easy to link results back to your own table.

Bulk use and limits

Instead of querying thousands of records one by one, feed your file into the hotel mapping flow; results come back via daily full and delta dumps. The Find Match API does not open a new ID for a record below 0.80; in the bulk ingestion flow, however, a new HM ID is opened for these records (the new_id decision). With the HM ID you find, you can also reach destination and hotel content data.

The response fields follow API v1; the exact schema is published on the developers page.

What is hotel mapping? The complete guide

API example

Request

Match lookup by name and coordinates
curl -X POST https://api.hotelmapping.org/v1/match \
  -H "X-API-Key: $HM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "res-55821",
    "name": "Sunset Bay Rsrt. & Spa - Adults",
    "city": "Belek",
    "country": "TR",
    "lat": 36.8539,
    "lng": 31.0556
  }'

Response

200 OK
{
  "reference": "res-55821",
  "decision": "auto_match",
  "hm_id": "HM-1048213",
  "name": "Sunset Bay Resort & Spa",
  "confidence": 0.984,
  "candidates": [
    { "hm_id": "HM-1048213", "confidence": 0.984, "distance_m": 42 },
    { "hm_id": "HM-1048390", "confidence": 0.412, "distance_m": 310 }
  ]
}

Code samples are illustrative; field names may change in the v1 release.

Frequently asked questions

What is the difference between the Find Match API and a supplier code lookup?

A supplier code lookup (GET /v1/suppliers/{supplier}/codes/{code}) directly returns the HM ID of a code that has already been mapped. The Find Match API, on the other hand, searches by name, address and coordinates for a record that has no code or is unknown to the system, and calculates a new score.

Which fields are required in the request?

A hotel name and location information (coordinates, or country, city and address) are required. Phone, website and postal code are optional but strengthen the score.

What should I do if I get a review decision?

Compare the candidates in the response by name, distance and score. The route for sending records you cannot decide on to specialist review (portal or API) has not been finalized yet. Specialist decisions are added to the model as training data.

Can I search with a Russian or Arabic name?

Yes. Cyrillic and Arabic script names are transliterated to Latin script during normalization; multilingual embedding similarity also contributes to the score. You do not need to translate the name yourself.

How can I try the API?

You can try it on sample data with a sandbox account.

Request a quote

Get your tailored quote

Send your request in three steps; we will email the quote to your work address. The request is non-binding.

  1. 1 Select solutions
  2. 2 Select suppliers
  3. 3 Leave your contact details