# Find-Match-API-Lösungen

> URL: https://hotelmapping.org/de/produkte/find-match-api-loesungen/ · Sprache: Deutsch

Die Find Match API nimmt einen einzelnen Hoteldatensatz (Name, Adresse, Koordinaten, falls vorhanden Telefon und Webadresse) entgegen und findet das Gegenstück in der hotelmapping.org-Datenbank. Die Antwort enthält die passende HM ID, einen Konfidenz-Score von 0 bis 1 und die auf diesem Score beruhende Entscheidung. Sie funktioniert auch für Datensätze ohne Anbietercode.

## Ihre Vorteile

- **Kein Anbietercode erforderlich:** Für Ihre Vertragshotels, Extranet-Datensätze oder einen Hotelnamen als Freitext genügen Name und Standortangaben.
- **Score und Entscheidung zusammen:** Jede Antwort enthält Konfidenz-Score und Entscheidungsfeld. Mit eigenen Geschäftsregeln können Sie zusätzlich eingrenzen, welche Datensätze Sie automatisch übernehmen.
- **Robust gegenüber Schreibabweichungen:** Abkürzungen, fehlende Zusätze sowie Namen in kyrillischer und arabischer Schrift durchlaufen die Normalisierung. Unterschiede wie "Rsrt." und "Resort" werden bei der Namensähnlichkeit auf Zeichen- und Wortebene verglichen.
- **Kandidatenliste:** Die wahrscheinlichsten Kandidaten kommen mit Entfernung und Score zurück; das erleichtert die Entscheidung bei Datensätzen, die geprüft werden müssen.

## Vorher und nachher

Datensatz ohne Anbietercode aus dem eigenen System des Reisebüros

**kontratli_oteller.csv**

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

Ergebnis der 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
  }
}
```

_Beispieldaten; Hotelname, Telefonnummer und Codes gehören zu keiner realen Unterkunft. Der russische Name wird transliteriert und nach Abtrennung des Zusatzes "Hotel" verglichen._

## So funktioniert es

1. **Anfrage:** An den Endpunkt POST /v1/match werden Hotelname und Standortangaben gesendet. Je mehr Koordinaten, Adresse, Telefon und Webadresse hinzukommen, desto stärker wird das Matching.
2. **Normalisierung:** Zusätze wie "Hotel", "Resort & Spa" oder "Otel" werden vom Namen getrennt; russische und arabische Namen werden transliteriert; die Telefonnummer wird ins internationale Format gebracht, die Webadresse auf die Domain reduziert.
3. **Kandidatensuche:** Der Datensatz wird nur mit Hotels in der Nähe verglichen: geografische Zelle von etwa 500 Metern, Namensähnlichkeit, gleiche Telefonnummer oder Domain.
4. **Scoring:** Namensähnlichkeit, mehrsprachige Embedding-Ähnlichkeit, Entfernung, Telefon- und Webübereinstimmung, Sterne und Postleitzahl ergeben zusammen einen Wahrscheinlichkeits-Score zwischen 0 und 1.
5. **Entscheidung:** Bei einem Score ab 0,97 wird auto_match zurückgegeben, zwischen 0,80 und 0,97 review, unter 0,80 no_match; bei no_match ist hm_id null. Die Antwort enthält zudem die wahrscheinlichsten Kandidaten.

## API-Beispiel

**Match-Suche mit Name und Koordinaten**

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

_Die Codebeispiele sind exemplarisch; Feldnamen können sich mit dem v1-Release ändern._

## Wann wird die Find Match API eingesetzt?

Das Produkt [Hotel-Mapping](https://hotelmapping.org/de/produkte/hotel-mapping-loesungen/) bindet Anbieterdateien gesammelt an HM IDs. Die Find Match API dient dagegen dazu, einen einzelnen Datensatz sofort abzufragen. Typische Einsatzbereiche:

- Ihre Vertragshotels oder Extranet-Datensätze einzeln an die [HM ID](https://hotelmapping.org/de/glossar/hm-id/) binden. Das gesammelte Mapping von Vertragshotels über das Portal ist geplant.
- Beispieldatensätze testen, bevor Sie mit einem neuen Anbieter zusammenarbeiten.
- Hotelnamen als Freitext in Buchungs-, CRM- oder Buchhaltungssystemen in die Standardkennung überführen.
- Einen Hotelnamen, der in ein Suchfeld oder einen KI-Assistenten eingegeben wird, zusammen mit den Standortangaben der richtigen Unterkunft zuordnen.

Die allgemeine Logik des Mappings erläutern wir im [Leitfaden zum Hotel-Mapping](https://hotelmapping.org/de/ratgeber/was-ist-hotel-mapping/).

## Das Entscheidungsfeld in der Antwort

| Konfidenz-Score | `decision` | Was ist zu tun? |
| --- | --- | --- |
| ab 0,97 | `auto_match` | Sie können die HM ID direkt verwenden |
| 0,80–0,97 | `review` | Kandidaten prüfen; auf Unterschiede bei Name, Entfernung und Telefon achten |
| unter 0,80 | `no_match` | `hm_id` ist null. Die Unterkunft ist möglicherweise noch nicht in der Datenbank; Name und Standort prüfen |

Die Schwellenwerte werden anhand des manuell annotierten Testsets eingestellt und können sich zwischen Versionen ändern. Aus welchen Signalen sich der Score zusammensetzt, erklären wir unter dem Begriff [Match-Score](https://hotelmapping.org/de/glossar/match-score/).

## Für bessere Ergebnisse

- **Senden Sie Koordinaten.** Die Kandidatensuche beginnt mit der geografischen Zelle. Fehlen Koordinaten, werden Stadt und Adresse verwendet; die Zahl der Kandidaten steigt, der Score sinkt meist. Zur Umwandlung von Adressen in Koordinaten siehe den Begriff [Geokodierung](https://hotelmapping.org/de/glossar/geokodierung/).
- **Fügen Sie Telefon und Webadresse hinzu.** Dieselbe Telefonnummer oder Domain ist ein starkes Matching-Signal.
- **Senden Sie den Namen unverändert.** Namen in kyrillischer oder arabischer Schrift werden per [Transliteration](https://hotelmapping.org/de/glossar/transliteration/) in lateinische Schrift überführt.
- **Nutzen Sie das Feld `reference`.** Ihre eigene Datensatzkennung kommt in der Antwort unverändert zurück; so lassen sich die Ergebnisse leichter mit Ihrer eigenen Tabelle verknüpfen.

## Batch-Nutzung und Limits

Anstatt Tausende Datensätze einzeln abzufragen, übergeben Sie Ihre Datei an den Hotel-Mapping-Ablauf; das Ergebnis kommt über den täglichen Voll- und Delta-Dump zurück. Die Find Match API legt für Datensätze unter 0,80 keine neue Kennung an; im Batch-Import dagegen wird für diese Datensätze eine neue HM ID angelegt (Entscheidung new_id). Mit der gefundenen HM ID erreichen Sie auch Daten zu [Destinationen](https://hotelmapping.org/de/produkte/destinations-mapping-loesungen/) und [Hotelinhalten](https://hotelmapping.org/de/produkte/hotelbeschreibungen-loesungen/).

Die Antwortfelder entsprechen der API v1; das endgültige Schema wird auf der [Entwicklerseite](https://hotelmapping.org/de/entwickler/) veröffentlicht.

## Häufig gestellte Fragen

### Was ist der Unterschied zwischen der Find Match API und der Abfrage per Anbietercode?

Die Abfrage per Anbietercode (GET /v1/suppliers/{supplier}/codes/{code}) liefert direkt die HM ID eines bereits zugeordneten Codes. Die Find Match API dagegen sucht einen Datensatz ohne Code oder mit im System unbekanntem Code anhand von Name, Adresse und Koordinaten und berechnet einen neuen Score.

### Welche Felder sind in der Anfrage Pflicht?

Erforderlich sind Hotelname und Standortangaben (Koordinaten oder Land, Stadt und Adresse). Telefon, Webadresse und Postleitzahl sind optional, verbessern aber den Score.

### Was soll ich tun, wenn die Entscheidung review lautet?

Vergleichen Sie die Kandidaten in der Antwort anhand von Name, Entfernung und Score. Der Weg, Datensätze, bei denen Sie nicht entscheiden können, an die Expertenprüfung zu senden (Portal oder API), steht noch nicht fest. Expertenentscheidungen fließen als Trainingsdaten in das Modell ein.

### Kann ich mit russischen oder arabischen Namen suchen?

Ja. Namen in kyrillischer und arabischer Schrift werden bei der Normalisierung transliteriert; auch die mehrsprachige Embedding-Ähnlichkeit fließt in den Score ein. Sie müssen den Namen nicht selbst übersetzen.

### Wie kann ich die API ausprobieren?

Mit einem Sandbox-Konto können Sie sie anhand von Beispieldaten testen.

## Verwandte Produkte

- [Hotel-Mapping-Lösungen](https://hotelmapping.org/de/produkte/hotel-mapping-loesungen/)
- [Destinations-Mapping-Lösungen](https://hotelmapping.org/de/produkte/destinations-mapping-loesungen/)
- [Hotelbeschreibungen-Lösungen](https://hotelmapping.org/de/produkte/hotelbeschreibungen-loesungen/)

## Verwandte Artikel

- [12 Fragen, die Sie bei der Auswahl einer Hotel-Mapping-API stellen sollten](https://hotelmapping.org/de/ratgeber/hotel-mapping-api-auswaehlen-12-fragen/)
- [Was ist Hotel-Mapping? So funktioniert es: der umfassende Leitfaden](https://hotelmapping.org/de/ratgeber/was-ist-hotel-mapping/)
- [Kosten von Hotel-Dubletten für Reisebüros: Konversion, Stornos und Kundenbeschwerden](https://hotelmapping.org/de/ratgeber/kosten-von-hotel-dubletten-fuer-reisebueros/)
