# API Türkiye

> API Türkiye, EKKASOFT'un geliştirdiği Türkiye adres verisi REST API'sidir. İl, ilçe, mahalle, cadde/sokak ve dış kapı kayıtlarını hiyerarşik listeler, yazım hatalarına toleranslı akıllı arama ve bileşen bazlı adres doğrulama ile uygulamalara taşır.

Temel bilgiler:

- Web sitesi ve müşteri portalı: https://apiturkiye.com
- API temel adresi: https://api.apiturkiye.com (yalnız API; site sayfaları ana alan adına yönlenir).
- Adres ve veri seti uçları `/v1` önekini kullanır; yanıtlar UTF-8 JSON'dur. Başarılı yanıtlar `data` ve uca göre `meta` içerir.
- Kimlik doğrulama yalnız `X-API-Key` başlığıyladır; Bearer token veya başka bir başlık kabul edilmez. Anahtar, paket onayından sonra müşteri portalında oluşturulur; tarayıcı koduna, herkese açık depolara veya loglara konmaz. Aynı müşteri hesabındaki anahtarlar hız sınırını ve günlük/aylık kotayı paylaşır.
- Katalog 81 il ve 973 ilçeyi kapsar; bunlara bağlı yaklaşık 73.500 mahalle, 1,28 milyon cadde/sokak ve 39,6 milyon dış kapı kaydı içerir. Bunlar yuvarlanmış katalog kayıt sayılarıdır, resmî idari istatistik değildir; kesin sayılar `GET /v1/meta` yanıtında. İl kodu (`code`) araç plaka koduyla aynıdır: 01 Adana, 06 Ankara, 34 İstanbul, 35 İzmir, 81 Düzce.
- `stableId`, API Türkiye'nin aynı kaynak kimliği için katalog sürümlerinden bağımsız ürettiği kalıcı kimliktir; resmî adres kodu veya resmî tescil numarası değildir. Entegrasyonlar referans olarak bunu saklamalıdır. Dış kapının sayısal `id` değeri yalnız ilgili katalog sürümüne aittir.
- Mahallelerin `locality.town` ve `locality.village` alanları kaynak yerleşim bağlamını verir ve aynı adlı mahalleleri ayırmaya yarar; resmî köy/belde sınıflandırması olarak yorumlanmaz.
- Her yanıt bir `X-Request-Id` başlığı taşır; sunucu hatalarında bu değer destek talebine eklenir. İletişim: info@ekkasoft.com

Sunulmayanlar: API Türkiye posta kodu, koordinat veya harita verisi, konumdan adres bulma (ters coğrafi kodlama), iç kapı (daire) numarası ve tek satırlık serbest adres metninin ayrıştırılmasını sunmaz. Adres doğrulama, ayrı gönderilen bileşenlerin katalogda birbiriyle ilişkisini kontrol eder; teslimat yapılabileceğinin veya adresin hukuken tescilli olduğunun garantisi değildir. Örnek kod ve adresleri gerçek katalog sonucu olarak kabul etmeyin; güncel fiyat için fiyatlandırma bölümünü, uygulanan kota ve yetkiler için hesaptaki paket bilgilerini esas alın.

Örnek istek: `curl https://api.apiturkiye.com/v1/provinces -H "X-API-Key: <API_ANAHTARINIZ>"` → `{ "data": [ { "stableId": "apt_v1_prv_...", "code": 34, "name": "İstanbul" }, ... ] }`

In English: API Türkiye is a REST API for Turkish address data (provinces, districts, neighbourhoods, streets and building numbers; about 73,500 neighbourhood, 1.28 million street and 39.6 million building-number records) with typo-tolerant autocomplete and component-based address validation. Base URL https://api.apiturkiye.com, authentication with the `X-API-Key` header, JSON responses; documentation is in Turkish at https://apiturkiye.com/docs.html. Postal codes, coordinates and reverse geocoding are not provided.

## Ürün ve paketler

- [Ürün özellikleri](https://apiturkiye.com/#features): İl → ilçe → mahalle → cadde/sokak → dış kapı adres hiyerarşisi ve sürümlü katalog.
- [API yetenekleri](https://apiturkiye.com/#capabilities): Fuzzy search, yazım hatası toleransı, Türkçe normalizasyon, bağlamsal arama, adres doğrulama, il/ilçe/mahalle ile daraltma, dış kapı listeleri ve katalog meta verisi. Herkese açık bir OpenAPI dosyası veya npm paketi yoktur; entegrasyon doğrudan HTTP/JSON ile yapılır.
- [Core paketi](https://apiturkiye.com/#pricing): Ücretsiz ve süresiz; günlük 1.000 API isteği, dakikada 60 istek. Tam adres hiyerarşisi ve akıllı arama içerir; adres doğrulama, veri seti geçmişi ve snapshot yetkilerini içermez.
- [Pro paketi](https://apiturkiye.com/#pricing): 500 TL/ay; aylık 200.000 API isteği, dakikada 300 istek. Core yeteneklerine ek olarak adres doğrulama ve veri seti geçmişi sunar.
- [Ultra paketi](https://apiturkiye.com/#pricing): 5.000 TL/ay; aylık 2.500.000 API isteği, dakikada 1.000 istek. Pro yeteneklerine ek olarak toplu veri seti snapshot erişimi sunar.
- [Enterprise paketi](https://apiturkiye.com/#pricing): Fiyat, kota ve hız limiti ihtiyaca göre belirlenir; yayımlanmış sabit bir ücret veya sınırsız kullanım taahhüdü yoktur.
- [Hesap oluşturma](https://apiturkiye.com/register.html): Ücretsiz hesap açın, portaldan paket erişimi talep edin; onaydan sonra API anahtarınızı portalda oluşturun. Enterprise başvurusu da portaldaki paket ekranından yapılır.
- [Canlı demo](https://apiturkiye.com/#demo): Ürünü ana sayfadaki sınırlı demo ile deneyin; demo, üretim API erişiminin yerine geçmez.

## API entegrasyonu

- [Başlangıç](https://apiturkiye.com/docs.html#start): Temel adres ve ilk HTTP isteği. Müşteri portalının `success` alanını adres API yanıtlarında beklemeyin.
- [Kimlik doğrulama ve yetkiler](https://apiturkiye.com/docs.html#auth): `X-API-Key`; listeler ve arama için `addresses:read`, doğrulama için `addresses:validate`, veri setleri için `datasets:read`, snapshot listesi/detayı için `snapshots:read`, indirme bağlantısı için `snapshots:download`.
- [Adres hiyerarşisi uçları](https://apiturkiye.com/docs.html#endpoints): `GET /v1/meta`, `/v1/provinces`, `/v1/provinces/{code}/districts`, `/v1/districts/{code}/neighborhoods`, `/v1/neighborhoods/{code}/streets` ve `/v1/streets/{code}/buildings`.
- [Katalog meta verisi ve güncellik](https://apiturkiye.com/docs.html#endpoints): `GET /v1/meta` aktif katalog adını, kayıt sayılarını ve devreye alınma zamanını (`activated_at`) döndürür; veri güncelliğini buradan kontrol edin.
- [Sabit kimlikler](https://apiturkiye.com/docs.html#identity): Referans olarak `stableId` saklayın; kaynak `code` eşleştirme içindir.
- [Sayfalama](https://apiturkiye.com/docs.html#pagination): Cadde/sokak ve dış kapı listelerinde `limit` 1–100, varsayılan 50; sonraki sayfa için `meta.nextCursor` kullanılır. İl, ilçe ve mahalle listeleri ilgili kapsamın tamamını tek yanıtta verir; mahalleleri ilk 100 kayıtla sınırlamayın.
- [Mahalle ve yerleşim bağlamı](https://apiturkiye.com/docs.html#locality): Aynı adlı mahalleleri `locality.town` ve `locality.village` ile ayırın; ilçedeki tüm kayıtları belediye merkezinin mahalleleri olarak yorumlamayın.
- [Akıllı adres arama](https://apiturkiye.com/docs.html#autocomplete): `GET /v1/autocomplete`; `q` 3–100 karakter, `limit` 1–20, varsayılan 10. İl, ilçe, mahalle ve sokak önerir; `provinceCode`, `districtCode`, `neighborhoodCode` ve `types` ile daraltılır. Dış kapılar arama kapsamında değildir; bir sokağın kapıları `/v1/streets/{code}/buildings` ucunda `q` ile numara önekine göre aranır.
- [Adres doğrulama](https://apiturkiye.com/docs.html#validation): `POST /v1/addresses/validate` (Pro ve üzeri); il, ilçe, mahalle, sokak ve dış kapı ayrı JSON bileşenleri olarak gönderilir. Eşleşmeme HTTP `200` ve `valid: false` döndürür; `failedAt`, `matched` ve `suggestions` alanlarını değerlendirin. Aynı adlı mahalleler belirsizse uç bunlardan birini kendiliğinden seçmez.
- [Veri setleri ve snapshot dosyaları](https://apiturkiye.com/docs.html#datasets): Aktif katalog, yayın geçmişi, sürüm detayları ve paket yetkisine bağlı toplu dosya erişimi. İndirilebilirliği `downloadAvailable` ile kontrol edin; listeleme yetkisini indirme yetkisi saymayın.
- [Hız sınırı ve kullanım kotası](https://apiturkiye.com/docs.html#quota): Hız sınırı dakika bazlıdır; kota Core'da günlük, Pro ve Ultra'da aylıktır. Günlük kota 00:00 UTC (03:00 TSİ), aylık kota sonraki ayın ilk günü aynı saatte yenilenir. Sınır nedeniyle reddedilen istekler kotadan düşülmez; `X-Quota-Limit`, `X-Quota-Remaining`, `X-Quota-Reset` ve `Retry-After` başlıklarını izleyin.
- [Hata yanıtları](https://apiturkiye.com/docs.html#errors): Kararı HTTP durumu ve `error.code` ile verin, mesaj metniyle değil. `400 invalid_request` yanıtındaki `details` hangi parametrenin neden reddedildiğini söyler; `401` anahtar sorununu, `403` yetki veya abonelik sorununu, `429` hız (`rate_limit_exceeded`) veya kota (`quota_exceeded`) aşımını bildirir. Yetki veya kota düzelmeden sürekli tekrar denemeyin.

## Rehberler

- [Blog](https://apiturkiye.com/blog): Adres verisi, entegrasyon, e-ticaret operasyonu ve kurumsal adres yönetimi üzerine rehberler; hafta içi her gün yeni yazı.
- [Blog RSS beslemesi](https://apiturkiye.com/blog/feed.xml): Yayımlanan son yazıların listesi.
- [Türkiye adres verileri](https://apiturkiye.com/blog/turkiye-adres-verileri-yapisi): İl, ilçe, mahalle, cadde/sokak ve dış kapı katmanlarının anlamı; dış kapı ile iç kapı farkı.
- [İl plaka kodları listesi](https://apiturkiye.com/blog/il-plaka-kodlari): 81 ilin plaka kodu ve plaka kodunun sistemlerde il kodu olarak kullanımı.
- [Türkiye il ilçe listesi](https://apiturkiye.com/blog/turkiye-il-ilce-listesi-json): İl ve ilçe listesini API'den JSON olarak almak ve güncel tutmak.
- [Açık adres nasıl yazılır](https://apiturkiye.com/blog/acik-adres-nasil-yazilir): Açık adresin bileşenleri, yazım sırası ve kısaltmalar.
- [Adres formu nasıl kurulur](https://apiturkiye.com/blog/il-ilce-mahalle-secimli-adres-formu): İl, ilçe ve mahalle seçimli adres formu; sunucu tarafı vekil ve `stableId` saklama.
- [İngilizce adres nasıl yazılır](https://apiturkiye.com/blog/ingilizce-adres-nasil-yazilir): Türkiye adresini çevirmeden Address Line 1/2, City ve State/Province alanlarına eşleştirme kuralları ve örnekler.
- [Hatalı adresin maliyeti](https://apiturkiye.com/blog/hatali-adres-maliyeti): Başarısız teslimat, müşteri hizmetleri, iade ve marka algısındaki maliyet; yapılandırılmış adrese geçiş.

## Durum, koşullar ve iletişim

- [Servis durumu](https://apiturkiye.com/status.html): Servisin güncel durumu ve yayımlanmış olaylar. JSON: `https://apiturkiye.com/status` (genel ve bileşen durumu), `https://apiturkiye.com/status/incidents`.
- [API kullanım koşulları](https://apiturkiye.com/api-kullanim-kosullari.html): API erişimi, kullanım sınırları, veri kullanımı ve hizmet koşulları.
- [Üyelik koşulları](https://apiturkiye.com/uyelik-kosullari.html): Hesap, üyelik ve müşteri sorumlulukları.
- [Gizlilik politikası](https://apiturkiye.com/gizlilik-politikasi.html): Gizlilik ve veri işleme yaklaşımı.
- [KVKK aydınlatma metni](https://apiturkiye.com/kvkk-aydinlatma.html): Kişisel verilerin işlenmesine ilişkin aydınlatma.
- [Güvenlik politikası](https://apiturkiye.com/guvenlik-politikasi.html): Güvenlik yaklaşımı ve güvenlik açığı bildirimi.
- [İptal ve iade politikası](https://apiturkiye.com/iptal-iade-politikasi.html): Paket iptali ve iade koşulları.
- [İletişim](mailto:info@ekkasoft.com): Ürün, paket ve entegrasyon soruları için EKKASOFT ile iletişim.

## Optional

- [Çerez politikası](https://apiturkiye.com/cerez-politikasi.html): Sitede çerez kullanımına ilişkin bilgiler.
- [KVKK başvurusu](https://apiturkiye.com/kvkk-basvuru.html): Kişisel verilerle ilgili hak talepleri için başvuru bilgileri.
- [robots.txt](https://apiturkiye.com/robots.txt): Tarayıcı robotları için erişim yönergeleri. Bu `llms.txt` rehberi erişim izni vermez ve robots.txt veya güvenlik kurallarını geçersiz kılmaz.
- [Sitemap](https://apiturkiye.com/sitemap.xml): Herkese açık sayfaların URL listesi.
- [Blog sitemap](https://apiturkiye.com/blog/sitemap.xml): Blog yazıları, kategori ve yazar sayfalarının URL listesi.