# Find Match API solutions

> URL: https://hotelmapping.org/en/products/find-match-api-solutions/ · Language: English

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**

```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**

```json
{
  "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. **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. **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. **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. **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. **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.

## API example

**Match lookup by name and coordinates**

```bash
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
  }'
```

**200 OK**

```json
{
  "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._

## When is the Find Match API used?

The [hotel mapping](https://hotelmapping.org/en/products/hotel-mapping-solutions/) 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](https://hotelmapping.org/en/glossary/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](https://hotelmapping.org/en/guide/what-is-hotel-mapping/).

## 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](https://hotelmapping.org/en/glossary/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](https://hotelmapping.org/en/glossary/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](https://hotelmapping.org/en/glossary/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](https://hotelmapping.org/en/products/destination-mapping-solutions/) and [hotel content](https://hotelmapping.org/en/products/hotel-descriptions-solutions/) data.

The response fields follow API v1; the exact schema is published on the [developers page](https://hotelmapping.org/en/developers/).

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

## Related products

- [Hotel mapping solutions](https://hotelmapping.org/en/products/hotel-mapping-solutions/)
- [Destination mapping solutions](https://hotelmapping.org/en/products/destination-mapping-solutions/)
- [Hotel descriptions solutions](https://hotelmapping.org/en/products/hotel-descriptions-solutions/)

## Related articles

- [12 questions to ask when choosing a hotel mapping API](https://hotelmapping.org/en/guide/12-questions-hotel-mapping-api/)
- [What is hotel mapping? How it works: a complete guide](https://hotelmapping.org/en/guide/what-is-hotel-mapping/)
- [What duplicate hotel listings cost an agency: conversion, cancellations and complaints](https://hotelmapping.org/en/guide/cost-of-duplicate-hotel-listings/)
