Решение Find Match API

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

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

  • Код поставщика не нужен

    Для ваших контрактных отелей, записей экстранета или названия отеля в свободном тексте достаточно названия и данных о местоположении.

  • Оценка и решение вместе

    В каждом ответе возвращаются оценка уверенности и поле решения. Какие записи принимать автоматически, можно также ограничить собственным бизнес-правилом.

  • Устойчивость к разнице в написании

    Сокращения, отсутствующие приставки, названия кириллицей и арабской вязью проходят нормализацию. Различия вроде «Rsrt.» и «Resort» сравниваются при оценке сходства названий на уровне символов и слов.

  • Список кандидатов

    Наиболее вероятные кандидаты возвращаются вместе с расстоянием и оценками; принимать решение по записям, требующим проверки, становится проще.

До и после

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

kontratli_oteller.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
{
  "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. 1

    Запрос

    На конечную точку POST /v1/match отправляются название отеля и данные о местоположении. Чем больше добавлено координат, адреса, телефона и веб-адреса, тем увереннее совпадение.

  2. 2

    Нормализация

    Из названия выделяются приставки и суффиксы вроде «Hotel», «Resort & Spa», «Otel»; русские и арабские названия транслитерируются в латиницу; телефон приводится к международному формату, веб-адрес сводится к доменному имени.

  3. 3

    Поиск кандидатов

    Запись сравнивается только с ближайшими отелями: географическая ячейка около 500 метров, сходство названий, тот же телефон или домен.

  4. 4

    Оценка

    Сходство названий, сходство многоязычных эмбеддингов, расстояние, совпадение телефона и сайта, звёздность и почтовый индекс объединяются в оценку вероятности от 0 до 1.

  5. 5

    Решение

    При оценке 0,97 и выше возвращается auto_match, в диапазоне 0,80–0,97 — review, ниже 0,80 — no_match; при no_match hm_id равен null. В ответ также входят наиболее вероятные кандидаты.

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

Продукт маппинг отелей пакетно привязывает файлы поставщиков к HM ID. Find Match API предназначен для мгновенного запроса по одной записи. Типичные сценарии:

  • Привязать ваши контрактные отели или записи экстранета по одному к HM ID. Пакетный маппинг контрактных отелей через портал планируется.
  • Попробовать пример записей до начала работы с новым поставщиком.
  • Преобразовать названия отелей в свободном тексте в системе бронирования, CRM или бухгалтерии в стандартный идентификатор.
  • Привязать название отеля, введённое в строку поиска или ИИ-ассистенту, к нужному объекту вместе с данными о местоположении.

Общую логику сопоставления мы описываем в руководстве по маппингу отелей.

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

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

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

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

  • Отправляйте координаты. Поиск кандидатов начинается с географической ячейки. Если координат нет, используются город и адрес; число кандидатов растёт, оценка, как правило, снижается. О преобразовании адреса в координаты см. термин геокодирование.
  • Добавляйте телефон и веб-адрес. Одинаковый номер телефона или домен — сильный сигнал совпадения.
  • Отправляйте название как есть. Названия кириллицей или арабской вязью преобразуются в латиницу с помощью транслитерации.
  • Используйте поле reference. Ваш собственный идентификатор записи возвращается в ответе без изменений; результаты проще привязать к вашей таблице.

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

Вместо того чтобы запрашивать тысячи записей по одной, передайте файл в процесс маппинга отелей; результат вернётся в ежедневных полных и дельта-dump. Для записей с оценкой ниже 0,80 Find Match API новый идентификатор не создаёт; при пакетном приёме для таких записей создаётся новый HM ID (решение new_id). По найденному HM ID вы также получаете доступ к данным о направлении и к контенту об отелях.

Поля ответа соответствуют API v1; точная схема публикуется на странице для разработчиков.

Что такое маппинг отелей? Подробное руководство

Пример API

Запрос

Поиск совпадения по названию и координатам
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
{
  "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 отличается от запроса по коду поставщика?

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

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

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

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

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

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

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

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

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

Запросить предложение

Получите индивидуальное предложение

Отправьте запрос в три шага, и мы пришлём предложение на ваш рабочий e-mail. Запрос ни к чему не обязывает.

  1. 1 Выберите решения
  2. 2 Выберите поставщиков
  3. 3 Оставьте контактные данные