# Find Match API çözümü

> URL: https://hotelmapping.org/tr/urunler/eslestirme-api-cozumu/ · Dil: Türkçe

Find Match API, elinizdeki tek bir otel kaydını (ad, adres, koordinat, varsa telefon ve web adresi) alır ve hotelmapping.org veritabanındaki karşılığını bulur. Yanıtta eşleşen HM ID, 0–1 arası güven skoru ve bu skora göre verilen karar döner. Tedarikçi kodu olmayan kayıtlar için de çalışır.

## Neler kazanırsınız

- **Tedarikçi kodu gerekmez:** Kontratlı otelleriniz, extranet kayıtlarınız veya serbest metin bir otel adı için ad ve konum bilgisi yeterlidir.
- **Skor ve karar birlikte:** Her yanıtta güven skoru ve karar alanı döner. Hangi kaydı otomatik kabul edeceğinizi kendi iş kuralınızla da sınırlayabilirsiniz.
- **Yazım farklarına dayanıklı:** Kısaltmalar, eksik ekler, Kiril ve Arap harfli adlar normalleştirmeden geçer. "Rsrt." ile "Resort" gibi farklar ad benzerliğinde karakter ve kelime düzeyinde karşılaştırılır.
- **Aday listesi:** En olası adaylar mesafe ve skorlarıyla birlikte döner; kontrol gereken kayıtlarda karar vermek kolaylaşır.

## Önce ve sonra

Acentenin kendi sisteminden, tedarikçi kodu olmayan kayıt

**kontratli_oteller.csv**

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

Find Match API sonucu

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

_Örnek veridir; otel adı, telefon ve kodlar gerçek bir tesise ait değildir. Rusça ad Latin harfe çevrilip "otel" eki ayrıldıktan sonra karşılaştırılır._

## Nasıl çalışır

1. **İstek:** POST /v1/match ucuna otel adı ve konum bilgisi gönderilir. Koordinat, adres, telefon ve web adresi eklendikçe eşleşme güçlenir.
2. **Normalleştirme:** Addan "Hotel", "Resort & Spa", "Otel" gibi ekler ayrılır; Rusça ve Arapça adlar Latin harfe çevrilir; telefon uluslararası biçime, web adresi alan adına indirgenir.
3. **Aday arama:** Kayıt yalnız yakınındaki otellerle karşılaştırılır: yaklaşık 500 metrelik coğrafi hücre, ad benzerliği, aynı telefon veya alan adı.
4. **Skorlama:** Ad benzerliği, çok dilli embedding benzerliği, mesafe, telefon ve web eşleşmesi, yıldız ve posta kodu birleşerek 0–1 arası bir olasılık skoru üretir.
5. **Karar:** Skor 0,97 ve üstüyse auto_match, 0,80–0,97 arasıysa review, 0,80 altındaysa no_match döner; no_match yanıtında hm_id null olur. Yanıtta en olası adaylar da yer alır.

## API örneği

**Ad ve koordinatla eşleşme arama**

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

_Kod örnekleri temsilidir; alan adları v1 yayınında değişebilir._

## Find Match API ne zaman kullanılır?

[Otel eşleştirme](https://hotelmapping.org/tr/urunler/otel-eslestirme-cozumu/) ürünü tedarikçi dosyalarını toplu olarak HM ID'ye bağlar. Find Match API ise tek bir kaydı anında sorgulamak içindir. Tipik kullanım alanları:

- Kontratlı otellerinizi veya extranet kayıtlarınızı tek tek [HM ID](https://hotelmapping.org/tr/sozluk/hm-id/)'ye bağlamak. Portal üzerinden toplu kontratlı otel eşleştirme planlanıyor.
- Yeni bir tedarikçiyle çalışmaya başlamadan önce örnek kayıtları denemek.
- Rezervasyon, CRM veya muhasebe sistemindeki serbest metin otel adlarını standart kimliğe çevirmek.
- Bir arama kutusuna veya yapay zekâ asistanına yazılan otel adını, konum bilgisiyle birlikte doğru tesise bağlamak.

Eşleştirmenin genel mantığını [otel eşleştirme rehberinde](https://hotelmapping.org/tr/rehber/otel-eslestirme-nedir/) anlatıyoruz.

## Yanıttaki karar alanı

| Güven skoru | `decision` | Ne yapmalı? |
| --- | --- | --- |
| 0,97 ve üstü | `auto_match` | HM ID'yi doğrudan kullanabilirsiniz |
| 0,80–0,97 | `review` | Adayları kontrol edin; ad, mesafe ve telefon farklarına bakın |
| 0,80 altı | `no_match` | `hm_id` null döner. Tesis veritabanında henüz olmayabilir; adı ve konumu kontrol edin |

Eşikler elle etiketlenmiş test setine göre ayarlanır ve sürümler arasında değişebilir. Skorun hangi sinyallerden oluştuğunu [eşleşme skoru](https://hotelmapping.org/tr/sozluk/eslesme-skoru/) teriminde açıklıyoruz.

## Daha iyi sonuç için

- **Koordinat gönderin.** Aday arama coğrafi hücreyle başlar. Koordinat yoksa şehir ve adres kullanılır; aday sayısı artar, skor genelde düşer. Adresi koordinata çevirme konusunu [geokodlama](https://hotelmapping.org/tr/sozluk/geokodlama/) teriminde bulabilirsiniz.
- **Telefon ve web adresi ekleyin.** Aynı telefon numarası veya alan adı güçlü bir eşleşme sinyalidir.
- **Adı olduğu gibi gönderin.** Kiril veya Arap harfli adlar [transliterasyon](https://hotelmapping.org/tr/sozluk/transliterasyon/) ile Latin harfe çevrilir.
- **`reference` alanını kullanın.** Kendi kayıt kimliğiniz yanıtta aynen döner; sonuçları kendi tablonuza bağlamak kolaylaşır.

## Toplu kullanım ve limitler

Binlerce kaydı tek tek sorgulamak yerine dosyanızı otel eşleştirme akışına verin; sonuç günlük tam ve delta dump ile döner. Find Match API 0,80 altındaki kayıt için yeni kimlik açmaz; toplu alım akışında ise bu kayıtlar için yeni bir HM ID açılır (new_id kararı). Bulunan HM ID ile [destinasyon](https://hotelmapping.org/tr/urunler/destinasyon-eslestirme-cozumu/) ve [otel içeriği](https://hotelmapping.org/tr/urunler/otel-aciklamalari-cozumu/) verisine de ulaşırsınız.

Yanıt alanları API v1 taslağıdır; kesin şema [geliştirici sayfasında](https://hotelmapping.org/tr/gelistiriciler/) yayımlanır.

## Sık sorulan sorular

### Find Match API ile tedarikçi kodu sorgulaması arasındaki fark nedir?

Tedarikçi kodu sorgulaması (GET /v1/suppliers/{supplier}/codes/{code}) daha önce eşleştirilmiş bir kodun HM ID'sini doğrudan getirir. Find Match API ise kodu olmayan ya da sistemde bilinmeyen bir kaydı ad, adres ve koordinatla arar ve yeni bir skor hesaplar.

### İstekte hangi alanlar zorunlu?

Otel adı ve konum bilgisi (koordinat ya da ülke, şehir ve adres) gerekir. Telefon, web adresi ve posta kodu isteğe bağlıdır ama skoru güçlendirir.

### review kararı gelirse ne yapmalıyım?

Yanıttaki adayları ad, mesafe ve skorla karşılaştırın. Karar veremediğiniz kayıtları uzman kontrolüne göndermenin yolu (portal veya API) henüz kesinleşmedi. Uzman kararları modele eğitim verisi olarak eklenir.

### Rusça veya Arapça adla arama yapabilir miyim?

Evet. Kiril ve Arap harfli adlar normalleştirme sırasında Latin harfe çevrilir; çok dilli embedding benzerliği de skora katılır. Adı sizin ayrıca çevirmeniz gerekmez.

### API'yi nasıl deneyebilirim?

Sandbox hesabıyla örnek veri üzerinde deneyebilirsiniz.

## İlgili ürünler

- [Otel eşleştirme çözümü](https://hotelmapping.org/tr/urunler/otel-eslestirme-cozumu/)
- [Destinasyon eşleştirme çözümü](https://hotelmapping.org/tr/urunler/destinasyon-eslestirme-cozumu/)
- [Otel açıklamaları çözümü](https://hotelmapping.org/tr/urunler/otel-aciklamalari-cozumu/)

## İlgili makaleler

- [Hotel mapping API seçerken sorulması gereken 12 soru](https://hotelmapping.org/tr/rehber/hotel-mapping-api-secerken-12-soru/)
- [Otel eşleştirme (hotel mapping) nedir? Nasıl çalışır? Kapsamlı rehber](https://hotelmapping.org/tr/rehber/otel-eslestirme-nedir/)
- [Mükerrer otel listelemenin acenteye maliyeti: dönüşüm, iptal ve müşteri şikâyeti](https://hotelmapping.org/tr/rehber/mukerrer-otel-maliyeti/)
