# Решение Find Match API

> URL: https://hotelmapping.org/ru/produkty/reshenie-find-match-api/ · Язык: Русский

Find Match API берёт одну имеющуюся у вас запись об отеле (название, адрес, координаты, при наличии телефон и веб-адрес) и находит её соответствие в базе hotelmapping.org. В ответе возвращаются подходящий HM ID, оценка уверенности от 0 до 1 и решение, принятое по этой оценке. Работает и для записей без кода поставщика.

## Что вы получаете

- **Код поставщика не нужен:** Для ваших контрактных отелей, записей экстранета или названия отеля в свободном тексте достаточно названия и данных о местоположении.
- **Оценка и решение вместе:** В каждом ответе возвращаются оценка уверенности и поле решения. Какие записи принимать автоматически, можно также ограничить собственным бизнес-правилом.
- **Устойчивость к разнице в написании:** Сокращения, отсутствующие приставки, названия кириллицей и арабской вязью проходят нормализацию. Различия вроде «Rsrt.» и «Resort» сравниваются при оценке сходства названий на уровне символов и слов.
- **Список кандидатов:** Наиболее вероятные кандидаты возвращаются вместе с расстоянием и оценками; принимать решение по записям, требующим проверки, становится проще.

## До и после

Запись из собственной системы агентства без кода поставщика

**kontratli_oteller.csv**

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

Результат Find Match API

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

_Это пример данных; название отеля, телефон и коды не относятся к реальному объекту. Русское название транслитерируется в латиницу, и после выделения слова «отель» выполняется сравнение._

## Как это работает

1. **Запрос:** На конечную точку POST /v1/match отправляются название отеля и данные о местоположении. Чем больше добавлено координат, адреса, телефона и веб-адреса, тем увереннее совпадение.
2. **Нормализация:** Из названия выделяются приставки и суффиксы вроде «Hotel», «Resort & Spa», «Otel»; русские и арабские названия транслитерируются в латиницу; телефон приводится к международному формату, веб-адрес сводится к доменному имени.
3. **Поиск кандидатов:** Запись сравнивается только с ближайшими отелями: географическая ячейка около 500 метров, сходство названий, тот же телефон или домен.
4. **Оценка:** Сходство названий, сходство многоязычных эмбеддингов, расстояние, совпадение телефона и сайта, звёздность и почтовый индекс объединяются в оценку вероятности от 0 до 1.
5. **Решение:** При оценке 0,97 и выше возвращается auto_match, в диапазоне 0,80–0,97 — review, ниже 0,80 — no_match; при no_match hm_id равен null. В ответ также входят наиболее вероятные кандидаты.

## Пример API

**Поиск совпадения по названию и координатам**

```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 }
  ]
}
```

_Примеры кода носят иллюстративный характер; названия полей могут измениться в релизе v1._

## Когда используется Find Match API?

Продукт [маппинг отелей](https://hotelmapping.org/ru/produkty/resheniya-dlya-mappinga-oteley/) пакетно привязывает файлы поставщиков к HM ID. Find Match API предназначен для мгновенного запроса по одной записи. Типичные сценарии:

- Привязать ваши контрактные отели или записи экстранета по одному к [HM ID](https://hotelmapping.org/ru/glossariy/hm-id/). Пакетный маппинг контрактных отелей через портал планируется.
- Попробовать пример записей до начала работы с новым поставщиком.
- Преобразовать названия отелей в свободном тексте в системе бронирования, CRM или бухгалтерии в стандартный идентификатор.
- Привязать название отеля, введённое в строку поиска или ИИ-ассистенту, к нужному объекту вместе с данными о местоположении.

Общую логику сопоставления мы описываем в [руководстве по маппингу отелей](https://hotelmapping.org/ru/rukovodstvo/chto-takoe-mapping-otelei/).

## Поле решения в ответе

| Оценка уверенности | `decision` | Что делать? |
| --- | --- | --- |
| 0,97 и выше | `auto_match` | HM ID можно использовать напрямую |
| 0,80–0,97 | `review` | Проверьте кандидатов; посмотрите на различия в названии, расстоянии и телефоне |
| Ниже 0,80 | `no_match` | `hm_id` возвращается как null. Объекта может ещё не быть в базе; проверьте название и местоположение |

Пороги настраиваются по вручную размеченному тестовому набору и могут меняться между версиями. Из каких сигналов складывается оценка, поясняется в термине [оценка совпадения](https://hotelmapping.org/ru/glossariy/otsenka-sovpadeniya/).

## Для лучшего результата

- **Отправляйте координаты.** Поиск кандидатов начинается с географической ячейки. Если координат нет, используются город и адрес; число кандидатов растёт, оценка, как правило, снижается. О преобразовании адреса в координаты см. термин [геокодирование](https://hotelmapping.org/ru/glossariy/geokodirovanie/).
- **Добавляйте телефон и веб-адрес.** Одинаковый номер телефона или домен — сильный сигнал совпадения.
- **Отправляйте название как есть.** Названия кириллицей или арабской вязью преобразуются в латиницу с помощью [транслитерации](https://hotelmapping.org/ru/glossariy/transliteratsiya/).
- **Используйте поле `reference`.** Ваш собственный идентификатор записи возвращается в ответе без изменений; результаты проще привязать к вашей таблице.

## Пакетное использование и лимиты

Вместо того чтобы запрашивать тысячи записей по одной, передайте файл в процесс маппинга отелей; результат вернётся в ежедневных полных и дельта-dump. Для записей с оценкой ниже 0,80 Find Match API новый идентификатор не создаёт; при пакетном приёме для таких записей создаётся новый HM ID (решение new_id). По найденному HM ID вы также получаете доступ к данным о [направлении](https://hotelmapping.org/ru/produkty/resheniya-dlya-mappinga-napravleniy/) и к [контенту об отелях](https://hotelmapping.org/ru/produkty/resheniya-dlya-opisaniy-oteley/).

Поля ответа соответствуют API v1; точная схема публикуется на [странице для разработчиков](https://hotelmapping.org/ru/razrabotchikam/).

## Часто задаваемые вопросы

### Чем Find Match API отличается от запроса по коду поставщика?

Запрос по коду поставщика (GET /v1/suppliers/{supplier}/codes/{code}) сразу возвращает HM ID ранее сопоставленного кода. Find Match API ищет запись, у которой нет кода или которая неизвестна в системе, по названию, адресу и координатам и рассчитывает новую оценку.

### Какие поля в запросе обязательны?

Нужны название отеля и данные о местоположении (координаты либо страна, город и адрес). Телефон, веб-адрес и почтовый индекс необязательны, но повышают оценку.

### Что делать, если пришло решение review?

Сравните кандидатов из ответа по названию, расстоянию и оценке. Способ отправить записи, по которым вы не можете принять решение, на проверку эксперту (портал или API) пока не определён. Решения экспертов добавляются в обучающие данные модели.

### Можно ли искать по русскому или арабскому названию?

Да. Названия кириллицей и арабской вязью при нормализации транслитерируются в латиницу; в оценку входит и сходство многоязычных эмбеддингов. Переводить название отдельно не нужно.

### Как можно попробовать API?

Вы можете попробовать его на примерах данных в sandbox-аккаунте.

## Связанные продукты

- [Решения для маппинга отелей](https://hotelmapping.org/ru/produkty/resheniya-dlya-mappinga-oteley/)
- [Решения для маппинга направлений](https://hotelmapping.org/ru/produkty/resheniya-dlya-mappinga-napravleniy/)
- [Решения для описаний отелей](https://hotelmapping.org/ru/produkty/resheniya-dlya-opisaniy-oteley/)

## Связанные статьи

- [12 вопросов, которые нужно задать при выборе API маппинга отелей](https://hotelmapping.org/ru/rukovodstvo/vybor-api-mappinga-otelei-12-voprosov/)
- [Что такое маппинг отелей (сопоставление отелей) и как он работает? Подробное руководство](https://hotelmapping.org/ru/rukovodstvo/chto-takoe-mapping-otelei/)
- [Стоимость дубликатов отелей для агентства: конверсия, отмены и жалобы клиентов](https://hotelmapping.org/ru/rukovodstvo/stoimost-dublikatov-otelei/)
