API Türkiye dokümantasyonu: il, ilçe, mahalle ve sokak API'si
API rehberi
Hesap bilgileri ve sayfa verileri yükleniyor.

API Türkiye dokümantasyonu: il, ilçe, mahalle ve sokak API'si

Entegrasyon rehberi: Türkiye adres hiyerarşisine sunucudan sunucuya güvenli şekilde bağlanın.

Başlangıç

Temel API adresi https://api.apiturkiye.com şeklindedir. Üretim anahtarınızı müşteri panelinde paketiniz onaylandıktan sonra oluşturabilirsiniz.

curl "https://api.apiturkiye.com/v1/provinces" \ -H "X-API-Key: apt_live_..."

Bu rehberdeki adresler, kodlar, sürümler ve yanıtlar örnektir. Aynı sonuçların aktif katalogda bulunacağı garanti edilmez; uygulamanızda liste/arama yanıtlarından aldığınız gerçek kimlikleri kullanın.

Kimlik doğrulama

Her /v1 isteğinde anahtarınızı X-API-Key başlığında gönderin. Anahtarı tarayıcı koduna, Git deposuna veya loglara yazmayın. Şüpheli durumda panelden iptal edip yenisini oluşturun.

X-API-Key: apt_live_your_api_key

Adres listeleri ve autocomplete addresses:read, doğrulama addresses:validate, veri setleri datasets:read, snapshot listesi/detayı snapshots:read, indirme bağlantısı snapshots:download yetkisi gerektirir. Yetkiler paketinizle belirlenir. Eksik özellik yetkisi 403 insufficient_scope, aktif olmayan paket 403 subscription_inactive döner.

Sabit kimlikler

Her adres nesnesindeki stableId, aynı kaynak kimliği yeni katalog sürümünde tekrar geldiğinde değişmez. Entegrasyonlar kalıcı referans olarak stableId saklamalıdır. Kaynak code alanı eşleştirme amacıyla korunur; dış kapı yanıtındaki sayısal id ise yalnız aktif katalog sürümüne aittir.

{ "stableId": "apt_v1_dor_...", "id": "88214", "code": "72503885", "doorNumber": "2", "label": "" }

Sayfalama

Cadde/sokak ve dış kapı listelerinde limit değeri 1–100 arasındadır; varsayılan 50'dir. Sonraki sayfa için yanıttaki meta.nextCursor değerini cursor olarak gönderin; null son sayfayı belirtir. İl, ilçe ve mahalle uçları ilgili kapsamın tamamını tek yanıtta verir; bu uçlarda sayfalama yoktur. Mahalle listesini ilk 100 kayıtla sınırlandırmayın.

Veri seti geçmişi ve snapshot listelerinde limit 1–100, varsayılan 20'dir ve cursor kullanılır. Autocomplete ise 1–20 öneri döner; varsayılan 10'dur ve cursor yoktur.

{ "data": [], "meta": { "nextCursor": null } }

Uç noktalar

GET/v1/meta
GET/v1/provinces
GET/v1/provinces/{code}/districts
GET/v1/districts/{code}/neighborhoods
GET/v1/neighborhoods/{code}/streets
GET/v1/streets/{code}/buildings

Arama, doğrulama ve veri seti uçlarının örnekleri aşağıdaki bölümlerdedir.

Mahalle ve yerleşim bilgisi

/v1/districts/{code}/neighborhoods yanıtı, mahalle adı ve kimliğinin yanında locality.town ve locality.village alanlarında kaynak yerleşim kodlarını ve adlarını verir. Aşağıdaki örnek Giresun/Merkez ilçesine aittir:

{ "stableId": "apt_v1_ngh_m8ZIfn90bcFrJdALHcxB7Q", "code": "34629", "name": "DEMİROLUK", "locality": { "town": { "code": "621", "name": "MERKEZ" }, "village": { "code": "14345", "name": "ÇAVUŞOĞLU" } } }

Aynı adlı kayıtları DEMİROLUK (ÇAVUŞOĞLU) gibi etiketlerle ayırt edebilirsiniz. Kimlik olarak stableId veya code kullanın; aynı adları birleştirmeyin.

Bu alanlar kaynaktaki belde/köy gruplarını gösterir; resmî yerleşim türü sınıflandırması değildir. village.name bir merkez veya belde adı da olabilir. İlçe listesi diğer bağlı yerleşimlerdeki kayıtları da içerdiğinden, toplam kayıt sayısı belediye merkezinin resmî mahalle sayısı olarak yorumlanmamalıdır. Mevcut kimlikler, adlar, sıralama ve listenin kapsamı korunur.

Akıllı adres arama

GET/v1/autocomplete

İl, ilçe, mahalle ve cadde/sokak önerilerini Türkçe yazım farklılıklarına ve küçük yazım hatalarına toleranslı arayın. Dış kapı araması bu uçta yoktur; kapı numarasını seçilen sokağın /buildings?q=... ucunda arayın.

curl --get "https://api.apiturkiye.com/v1/autocomplete" \ --data-urlencode "q=Bağdat Cadessi" \ --data-urlencode "provinceCode=34" \ --data-urlencode "types=street" \ --data-urlencode "limit=5" \ -H "X-API-Key: apt_live_..."
  • q zorunludur: 3–100 karakter; normalize edilmiş sorgu da en az 3 karakter olmalıdır.
  • provinceCode, districtCode, neighborhoodCode aramayı coğrafi kapsamla sınırlar.
  • types: all, province, district, neighborhood, street; varsayılan all.
  • limit: 1–20; varsayılan 10. Cursor kullanılmaz.
{ "data": [{ "type": "street", "stableId": "apt_v1_str_...", "code": "719917310", "name": "Bağdat Caddesi", "label": "Bağdat Caddesi, Caddebostan, Kadıköy, İstanbul", "matchType": "fuzzy", "score": 0.913, "province": { "code": "34", "name": "İstanbul" }, "district": { "code": "1421", "name": "Kadıköy" }, "neighborhood": { "code": "194073", "name": "Caddebostan" } }], "meta": { "query": "bagdat caddesi", "nameQuery": "bagdat caddesi", "limit": 5 } }

matchType değeri exact, prefix, word_prefix veya fuzzy olabilir. score sıralama içindir; adresin geçerli veya teslimata uygun olduğunun kanıtı değildir. Sonuç türüne göre district ve neighborhood null olabilir. locality yalnız mahalle liste ucunda bulunur.

Adres doğrulama

POST/v1/addresses/validate

Gerekli yetki: addresses:validate. Ayrı adres bileşenlerini il → ilçe → mahalle → cadde/sokak → dış kapı sırasıyla aktif katalogda doğrular.

curl "https://api.apiturkiye.com/v1/addresses/validate" \ -H "X-API-Key: apt_live_..." \ -H "Content-Type: application/json" \ --data '{"province":"İstanbul","district":"Kadıköy","neighborhood":"Caferağa Mahallesi","street":"Moda Caddesi","doorNumber":"12"}'

province, district, neighborhood, street ve doorNumber zorunlu metin alanlarıdır; üst uzunluk sınırları sırasıyla 100, 100, 150, 200 ve 80 karakterdir. İsteğe bağlı doorId, dış kapı listesindeki id değeridir; code veya stableId değildir. Aynı numaralı farklı kapı kayıtlarını ayırmak için kullanılabilir.

Tam ve tekil eşleşmede data.valid: true, data.failedAt: null, data.normalizedAddress, data.components ve meta.datasetVersion döner. components içinde province, district, neighborhood, street, door yer alır. Ad bileşenleri { stableId, code, name }, kapı ise { stableId, id, code, doorNumber, label } biçimindedir; kodlar metindir.

{ "data": { "valid": true, "failedAt": null, "normalizedAddress": "CAFERAĞA MAHALLESİ, MODA CADDESİ No:12, KADIKÖY/İSTANBUL", "components": { "province": { "stableId": "apt_v1_prv_...", "code": "34", "name": "İSTANBUL" }, "district": { "stableId": "apt_v1_dst_...", "code": "1421", "name": "KADIKÖY" }, "neighborhood": { "stableId": "apt_v1_ngh_...", "code": "194073", "name": "CAFERAĞA MAHALLESİ" }, "street": { "stableId": "apt_v1_str_...", "code": "173405", "name": "MODA CADDESİ" }, "door": { "stableId": "apt_v1_dor_...", "id": "88214", "code": "43103743", "doorNumber": "12", "label": "" } } }, "meta": { "datasetVersion": "ae0a3bb4-1e32-4788-93c0-1490447bedf1" } }

Eşleşme yoksa veya birden fazla kesin aday varsa HTTP 200 korunur; uygulamanız data.valid alanını kontrol etmelidir:

{ "data": { "valid": false, "failedAt": "district", "matched": { "province": { "stableId": "apt_v1_prv_...", "code": "34", "name": "İSTANBUL" } }, "suggestions": [{ "stableId": "apt_v1_dst_...", "code": "1421", "name": "KADIKÖY" }] } }

failedAt: province, district, neighborhood, street veya doorNumber. matched önceki eşleşmeleri, suggestions aynı üst kapsam içindeki en fazla beş adayı gösterir; öneriler boş olabilir. Eksik/hatalı gövde 400 döner. Yerleşim alanları eklenmesi bu gövdeyi değiştirmemiştir; köy/belde filtresi kabul edilmez ve aynı adlı mahallelerden biri otomatik seçilmez.

Veri setleri ve snapshot dosyaları

datasets:read yetkisiyle aktif sürümü, yayın geçmişini ve sürüm detayını okuyabilirsiniz. Sürüm kimlikleri UUID biçimindedir; örnek kimlikler yerine yanıttan aldığınız değerleri kullanın.

# Aktif sürüm curl "https://api.apiturkiye.com/v1/datasets/current" \ -H "X-API-Key: apt_live_..." # Yayın geçmişi: limit 1–100, varsayılan 20; cursor desteklenir curl "https://api.apiturkiye.com/v1/datasets?limit=20" \ -H "X-API-Key: apt_live_..." # Sürüm detayı curl "https://api.apiturkiye.com/v1/datasets/ae0a3bb4-1e32-4788-93c0-1490447bedf1" \ -H "X-API-Key: apt_live_..."

Yanıtta datasetVersion, name, status, checksum: { algorithm, value }, counts, importedAt ve publishedAt bulunur. counts il, ilçe, yerleşim, mahalle, sokak, sokak-mahalle ilişkisi ve dış kapı sayılarını verir. Yayın geçmişi active ve retired sürümleri data dizisinde, meta.nextCursor ile döner. capabilities genel özellik bayrağıdır; bir dosyanın indirilebilirliğini snapshot yanıtındaki downloadAvailable ile kontrol edin.

Dosya listesi, detay ve indirme

# snapshots:read — liste; limit 1–100, varsayılan 20 curl "https://api.apiturkiye.com/v1/datasets/ae0a3bb4-1e32-4788-93c0-1490447bedf1/snapshots?limit=20" \ -H "X-API-Key: apt_live_..." # snapshots:read — dosya detayı curl "https://api.apiturkiye.com/v1/datasets/ae0a3bb4-1e32-4788-93c0-1490447bedf1/snapshots/c85b6fc3-912c-44e2-8427-724742bb71b6" \ -H "X-API-Key: apt_live_..." # snapshots:download — kısa ömürlü indirme bağlantısı curl "https://api.apiturkiye.com/v1/datasets/ae0a3bb4-1e32-4788-93c0-1490447bedf1/snapshots/c85b6fc3-912c-44e2-8427-724742bb71b6/download-url" \ -H "X-API-Key: apt_live_..."

Snapshot durumları pending, building, ready, failed olabilir. Yanıt; snapshotId, datasetVersion, entity, format, compression, status, sizeBytes, recordCount, checksum, downloadAvailable ve zaman alanlarını içerir. Hazır olmayan dosyanın boyutu, kayıt sayısı veya checksum'u null olabilir.

İndirme bağlantısı data.url, data.expiresAt, data.maxDownloads alanlarını verir. Dönen URL'yi hostname'i dahil aynen kullanın. Varsayılan geçerlilik 5 dakika, kullanım sınırı 3'tür; yanıttaki gerçek değerleri esas alın. İmzalı URL ile indirmede X-API-Key gerekmez; URL'deki token yetki taşır, paylaşmayın veya loglamayın. Dosyanın SHA-256 değerini checksum.value ile karşılaştırın.

Hata yanıtları

Hatalar error.code ve error.message alanlarını içerir; türe göre ek alanlar olabilir. Kararlarınızı mesaj metnine değil HTTP durumuna ve error.code değerine göre verin.

  • 400: invalid_request, invalid_cursor, invalid_code, invalid_query — gövde, parametre, cursor veya sorgu geçersiz.
  • 401 invalid_api_key: anahtar eksik, geçersiz, süresi dolmuş veya iptal edilmiş.
  • 403 insufficient_scope: özellik yetkisi yok; requiredScope alanını kontrol edin.
  • 403 subscription_inactive: paket aktif değil; subscriptionStatus alanını kontrol edin.
  • 403 forbidden: temel adres okuma yetkisi yok.
  • 404 dataset_not_found veya snapshot_not_found: yayınlanmış sürüm veya erişilebilir dosya bulunamadı.
  • 429 rate_limit_exceeded: hız sınırı. 429 quota_exceeded: paket kotası.
  • 503 catalog_unavailable: aktif katalog geçici olarak yok.
{ "error": { "code": "invalid_api_key", "message": "Geçerli bir X-API-Key başlığı zorunludur." } }

İmzalı indirme ucunda ayrıca 401 invalid_download_token (geçersiz/süresi dolmuş URL), 429 download_limit_exceeded (kullanım sınırı) ve 503 snapshot_file_unavailable (dosya geçici olarak erişilemiyor) görülebilir. 401/403 için anahtar, paket veya yetki düzeltilmeden otomatik tekrar yapmayın.

Hız sınırı ve paket kotası

429 iki farklı sınırı bildirir. rate_limit_exceeded: API anahtarı bazlı hız sınırı aşıldı; pencere varsayılan 60 saniyedir. Retry-After saniyesini bekleyin, X-RateLimit-Limit ve X-RateLimit-Remaining başlıklarını izleyin.

quota_exceeded: günlük (Core) veya aylık (Pro, Ultra) paket kotası doldu. Core paketinin günlük limiti 1.000 istektir. Aynı müşteri hesabındaki anahtarlar ortak kotayı kullanır. Gerçek sınırı panelden ve yanıttaki limit değerinden okuyun. period değeri day veya month, resetAt ise yenilenme zamanıdır.

Kotalar UTC takvimine göre sayılır: günlük kota ertesi gün 00:00 UTC (03:00 TSİ), aylık kota sonraki ayın ilk günü 00:00 UTC (03:00 TSİ) yenilenir. 429 ile reddedilen çağrılar kotanızdan düşülmez; diğer HTTP hata yanıtlarının ücretsiz olduğunu varsaymayın.

Kota uygulanıyorsa X-Quota-Limit, X-Quota-Remaining ve X-Quota-Reset (Unix saniyesi) başlıklarıyla kalan kotanızı izleyebilirsiniz; bunların her uçta veya her hata yanıtında bulunacağını varsaymayın.

{ "error": { "code": "quota_exceeded", "message": "Paketinizin günlük 1.000 istek kotası doldu. Kotanız 09.10.2026 03:00 (TSİ) itibarıyla yenilenecek. Daha yüksek limit için paketinizi yükseltebilirsiniz.", "period": "day", "limit": 1000, "resetAt": "2026-10-09T00:00:00.000Z" } }

Kota hatasında resetAt zamanını bekleyin veya paket değişikliği talep edin; aynı çağrıyı sürekli yeniden denemeyin.