# Soluciones de Find Match API

> URL: https://hotelmapping.org/es/productos/soluciones-find-match-api/ · Idioma: Español

Find Match API toma un único registro de hotel que usted tenga (nombre, dirección, coordenadas y, si los hay, teléfono y web) y encuentra su equivalente en la base de datos de hotelmapping.org. La respuesta devuelve el HM ID coincidente, una puntuación de confianza de 0 a 1 y la decisión asignada según esa puntuación. También funciona con registros que no tienen código de proveedor.

## Qué ganará

- **No requiere código de proveedor:** Para sus hoteles contratados, registros de extranet o un nombre de hotel en texto libre, bastan el nombre y los datos de ubicación.
- **Puntuación y decisión juntas:** Cada respuesta incluye la puntuación de confianza y un campo de decisión. También puede limitar con su propia regla de negocio qué registros aceptar automáticamente.
- **Tolera diferencias de escritura:** Las abreviaturas, los sufijos omitidos y los nombres en cirílico o árabe pasan por la normalización. Diferencias como "Rsrt." y "Resort" se comparan a nivel de carácter y de palabra en la similitud de nombre.
- **Lista de candidatos:** Los candidatos más probables se devuelven con su distancia y su puntuación; decidir sobre los registros que requieren revisión resulta más fácil.

## Antes y después

Registro sin código de proveedor del sistema propio de la agencia

**kontratli_oteller.csv**

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

Resultado de 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
  }
}
```

_Datos de ejemplo; el nombre del hotel, el teléfono y los códigos no corresponden a un establecimiento real. El nombre en ruso se compara tras transliterarlo al alfabeto latino y separar el sufijo "hotel"._

## Cómo funciona

1. **Petición:** Se envían a POST /v1/match el nombre del hotel y los datos de ubicación. La coincidencia se refuerza a medida que se añaden coordenadas, dirección, teléfono y web.
2. **Normalización:** Se separan del nombre sufijos como "Hotel", "Resort & Spa" u "Otel"; los nombres en ruso y árabe se transliteran al alfabeto latino; el teléfono se lleva al formato internacional y la web se reduce al nombre de dominio.
3. **Búsqueda de candidatos:** El registro se compara solo con los hoteles cercanos: celda geográfica de unos 500 metros, similitud de nombre, mismo teléfono o mismo dominio.
4. **Puntuación:** La similitud de nombre, la similitud de embeddings multilingües, la distancia, la coincidencia de teléfono y web, las estrellas y el código postal se combinan en una puntuación de probabilidad de 0 a 1.
5. **Decisión:** Con una puntuación de 0,97 o más se devuelve auto_match, entre 0,80 y 0,97 review y por debajo de 0,80 no_match; en la respuesta no_match, hm_id es null. La respuesta incluye también los candidatos más probables.

## Ejemplo de API

**Búsqueda de coincidencia por nombre y coordenadas**

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

_Los ejemplos de código son ilustrativos; los nombres de los campos pueden cambiar en la versión v1._

## ¿Cuándo se usa Find Match API?

El producto de [mapeo hotelero](https://hotelmapping.org/es/productos/soluciones-mapeo-hotelero/) vincula por lotes los archivos de proveedor a HM ID. Find Match API, en cambio, sirve para consultar al instante un único registro. Usos típicos:

- Vincular uno a uno sus hoteles contratados o registros de extranet a un [HM ID](https://hotelmapping.org/es/glosario/hm-id/). El mapeo masivo de hoteles contratados desde el portal está previsto.
- Probar registros de ejemplo antes de empezar a trabajar con un nuevo proveedor.
- Convertir en una identidad estándar los nombres de hotel en texto libre de su sistema de reservas, CRM o contabilidad.
- Vincular al establecimiento correcto, junto con los datos de ubicación, el nombre de hotel escrito en un cuadro de búsqueda o en un asistente de inteligencia artificial.

La lógica general del mapeo se explica en la [guía de mapeo hotelero](https://hotelmapping.org/es/guia/que-es-mapeo-hotelero/).

## El campo de decisión de la respuesta

| Puntuación de confianza | `decision` | Qué hacer |
| --- | --- | --- |
| 0,97 o más | `auto_match` | Puede usar el HM ID directamente |
| 0,80–0,97 | `review` | Revise los candidatos; fíjese en las diferencias de nombre, distancia y teléfono |
| Por debajo de 0,80 | `no_match` | `hm_id` devuelve null. Puede que el establecimiento aún no esté en la base de datos; compruebe el nombre y la ubicación |

Los umbrales se ajustan con un conjunto de prueba etiquetado manualmente y pueden cambiar entre versiones. Explicamos de qué señales se compone la puntuación en el término [puntuación de coincidencia](https://hotelmapping.org/es/glosario/puntuacion-de-coincidencia/).

## Para obtener mejores resultados

- **Envíe las coordenadas.** La búsqueda de candidatos comienza con la celda geográfica. Sin coordenadas se usan la ciudad y la dirección; aumenta el número de candidatos y la puntuación suele bajar. Sobre cómo convertir una dirección en coordenadas, consulte el término [geocodificación](https://hotelmapping.org/es/glosario/geocodificacion/).
- **Añada teléfono y web.** El mismo número de teléfono o el mismo dominio es una señal de coincidencia sólida.
- **Envíe el nombre tal cual.** Los nombres en cirílico o árabe se pasan al alfabeto latino mediante [transliteración](https://hotelmapping.org/es/glosario/transliteracion/).
- **Use el campo `reference`.** Su propio ID de registro vuelve intacto en la respuesta; resulta más fácil vincular los resultados a su propia tabla.

## Uso por lotes y límites

En lugar de consultar miles de registros uno a uno, entregue su archivo al flujo de mapeo hotelero; el resultado vuelve en el dump diario completo y delta. Find Match API no abre una nueva identidad para un registro por debajo de 0,80; en el flujo de ingesta por lotes, en cambio, para esos registros se abre un nuevo HM ID (decisión new_id). Con el HM ID encontrado también accede a los datos de [destino](https://hotelmapping.org/es/productos/soluciones-mapeo-destinos/) y de [contenido hotelero](https://hotelmapping.org/es/productos/soluciones-descripciones-hoteles/).

Los campos de la respuesta siguen la API v1; el esquema definitivo se publica en la [página para desarrolladores](https://hotelmapping.org/es/desarrolladores/).

## Preguntas frecuentes

### ¿Qué diferencia hay entre Find Match API y la consulta por código de proveedor?

La consulta por código de proveedor (GET /v1/suppliers/{supplier}/codes/{code}) devuelve directamente el HM ID de un código ya mapeado. Find Match API, en cambio, busca por nombre, dirección y coordenadas un registro que no tiene código o que el sistema no conoce, y calcula una nueva puntuación.

### ¿Qué campos son obligatorios en la petición?

Se necesitan el nombre del hotel y los datos de ubicación (coordenadas, o país, ciudad y dirección). El teléfono, la web y el código postal son opcionales, pero refuerzan la puntuación.

### ¿Qué debo hacer si llega la decisión review?

Compare los candidatos de la respuesta por nombre, distancia y puntuación. La vía para enviar a revisión de un especialista los registros sobre los que no pueda decidir (portal o API) aún no está decidida. Las decisiones de los especialistas se incorporan al modelo como datos de entrenamiento.

### ¿Puedo buscar con un nombre en ruso o en árabe?

Sí. Los nombres en cirílico y en árabe se transliteran al alfabeto latino durante la normalización; la similitud de embeddings multilingües también interviene en la puntuación. No necesita traducir el nombre por su cuenta.

### ¿Cómo puedo probar la API?

Puede probarla con datos de ejemplo mediante una cuenta sandbox.

## Productos relacionados

- [Soluciones de mapeo hotelero](https://hotelmapping.org/es/productos/soluciones-mapeo-hotelero/)
- [Soluciones de mapeo de destinos](https://hotelmapping.org/es/productos/soluciones-mapeo-destinos/)
- [Soluciones de descripciones de hoteles](https://hotelmapping.org/es/productos/soluciones-descripciones-hoteles/)

## Artículos relacionados

- [12 preguntas que hay que hacer al elegir una API de mapeo hotelero](https://hotelmapping.org/es/guia/12-preguntas-elegir-api-mapeo-hotelero/)
- [¿Qué es el mapeo hotelero (hotel mapping) y cómo funciona? Guía completa](https://hotelmapping.org/es/guia/que-es-mapeo-hotelero/)
- [Coste de los hoteles duplicados para la agencia: conversión, cancelaciones y quejas de clientes](https://hotelmapping.org/es/guia/coste-hoteles-duplicados/)
