Türkiye il, ilçe ve mahalle listesi API
Adres formundaki il → ilçe → mahalle açılır listelerini tek bir uç noktadan doldurun. Geo API, Türkiye'nin 81 ilini, 973 ilçesini ve TÜİK'in resmî listesindeki yaklaşık 50.000 mahalle ile köyün tamamını kalıcı kimlikleriyle JSON olarak verir. Veriler resmî ve açık kaynaklardan güncel tutulur.
Nasıl çalışır
/v1/places?parent= bir yerin bir alt düzeyini döndürür: parent=TR 81 ili, parent=TR-34 İstanbul'un 39 ilçesini, bir ilçenin kimliği de o ilçenin mahalle ve köylerini verir. Her satırda kimlik, ad, tür, yerel tür (il, ilçe, mahalle, köy) ve düzey bulunur.
Liste, arama ve yer ayrıntısı uç noktaları anahtarsız çalışır: IPv4 adresi ya da IPv6 /64 başına UTC gününde 1.000 istek ücretsiz; bu hak bütün anahtarsız uç noktalarda (meta, countries, countries/{cc}, places, places/{id}, phone) ortaktır. Yanıttaki X-RateLimit-Remaining başlığı kalan hakkı gösterir. Daha yüksek hacim ya da sunucudan yapılan çağrılar için bir API anahtarı ya da Apify Actor kullanın.
Kalıcı kimlikler ve resmî liste
İller ISO 3166-2 koduyla gelir (İstanbul TR-34). İlçe, mahalle ve köylerin kimliği TR- artı 8 karakterden oluşan kalıcı bir koddur (örneğin TR-PG39B8X4); bir mahallenin kimliği hiçbir zaman başka bir yere verilmez. Veritabanınızda adı değil kimliği saklayın: ad değişse de kayıt aynı yeri gösterir.
Mahalle ve köyler TÜİK'in Adrese Dayalı Nüfus Kayıt Sistemi listesinden gelir; her satırın local_type alanı mahalle ya da köy der. Bolu'nun Dörtdivan ilçesinde 8 mahalle ve 24 köy vardır; İstanbul'un Şile ilçesi gibi büyükşehir ilçelerinde yalnız mahalle bulunur.
Yazarken arama ve yerin tam yolu
Yazarken arama için /v1/places?q=kadikoy&country=TR kullanın: büyük/küçük harf, aksan ve ı/İ farkı yok sayılır, her aday üst birimleriyle gelir. /v1/places/{id} bir yerin adını, merkez koordinatını, nüfusunu ve path alanında ülkeden başlayan üst birimlerini verir: Kadıköy'deki bir mahallenin path'i Türkiye › İstanbul › Kadıköy'dür.
Aynı uç nokta dünya için de çalışır: parent=DE Almanya'nın eyaletlerini verir. 226 ülkede yaklaşık 3.900 birinci düzey bölge (eyalet, il) vardır.
Türkiye için hangi düzeyler var?
Geo API Türkiye'yi üç düzeyde verir: il, ilçe ve mahalle/köy. Mahalle ve köy düzeyinde 50.437 birim vardır ve liste TÜİK'in resmî listesinden (Adrese Dayalı Nüfus Kayıt Sistemi) gelir. Tablo her düzeyde listenin tam mı kısmi mi olduğunu ve kaç birimin sınırı olduğunu gösterir; sayılar sayfa yayımlanırken canlı API'den alınır.
| Düzey | Birim | Sayı | Liste | Sınır |
|---|---|---|---|---|
| 1 | il | 81 | tam | 81 / 81 birimin sınırı var |
| 2 | ilçe | 973 | tam | 973 / 973 birimin sınırı var |
| 3 | mahalle/köy | 50.437 | tam | 13.075 / 50.437 birimin sınırı var |
Mahalle ve köy sınırları kısmidir: 13.075 birimin sınırı vardır. Sınırı olmayan bir mahalle listede yer alır, ama koordinattan yer bulmada dönmez; böyle bir noktada yanıt ilçede biter. Ayrıntı ülke ülke kapsam sayfasındadır.
Ülke ülke kapsam ·API dokümantasyonu ·Servis durumu
Liste çekin: il, ilçe, mahalle
/v1/places?parent= bir yerin bir alt düzeyini döndürür: bir ülkenin kimliği illeri, bir ilin kimliği ilçeleri, bir ilçenin kimliği o ilçenin resmî mahalle ve köylerini verir. Her satırda kalıcı kimlik, ad ve tür gelir; veritabanınızda adı değil kimliği saklayın. Aşağıdaki örnek canlı API tanımından üretilir.
curl
curl "https://api.forlab.io/geo/v1/places?parent=TR-35&lang=tr%2Cen&limit=10&offset=0"JavaScript
const res = await fetch("https://api.forlab.io/geo/v1/places?parent=TR-35&lang=tr%2Cen&limit=10&offset=0");
const { data } = await res.json();Python
import requests
res = requests.get("https://api.forlab.io/geo/v1/places?parent=TR-35&lang=tr%2Cen&limit=10&offset=0", timeout=10)
data = res.json()["data"]Koordinattan mahalle bulun (point-in-polygon)
Bir enlem ve boylam gönderin; Geo API noktayı gerçek sınırlarla sınar (point-in-polygon) ve noktayı içeren ülkeyi, ili, ilçeyi ve sınırı olan yerlerde mahalleyi döndürür. Nokta denizdeyse ya da hiçbir birimin içinde değilse tahmin yürütmez, boş liste döner. 13.075 mahalle ve köyün sınırı olduğundan bazı noktalarda yanıt ilçede biter.
curl
curl -H "Authorization: Bearer $GEO_API_KEY" "Authorization: Bearer $GEO_API_KEY"JavaScript
const res = await fetch("Authorization: Bearer $GEO_API_KEY", {
headers: { Authorization: `Bearer ${process.env.GEO_API_KEY}` },
});
const { data } = await res.json();Python
import os, requests
res = requests.get(
"Authorization: Bearer $GEO_API_KEY",
headers={"Authorization": f"Bearer {os.environ['GEO_API_KEY']}"},
timeout=10,
)
data = res.json()["data"]Örnek istek ve yanıt
Bolu'nun Dörtdivan ilçesindeki mahalle ve köylerin ilk dördü. Anahtar gerekmez; meta.total listenin tamamını (32) söyler, limit ve offset ile sayfalayın.
İstek
curl "https://api.forlab.io/geo/v1/places?parent=TR-7N6BAMXN&limit=4"Yanıttan bir kesit
{
"data": [
{ "id": "TR-PG39B8X4", "name": "Adakınık", "type": "neighborhood", "local_type": "mahalle", "level": 3 },
{ "id": "TR-72TKWWHE", "name": "Adaköy", "type": "neighborhood", "local_type": "köy", "level": 3 },
{ "id": "TR-VPG03CA4", "name": "Aşağıdüğer", "type": "neighborhood", "local_type": "köy", "level": 3 },
{ "id": "TR-36WGHZ2G", "name": "Aşağısayık", "type": "neighborhood", "local_type": "köy", "level": 3 }
],
"meta": { "total": 32, "limit": 4, "offset": 0, … }
}Aynı iş Apify Actor ile
Anahtar almadan ya da toplu iş için Geo Reference Actor'üne bir liste verin; her öğe bir sonuç satırı olur ve gönderdiğiniz değer satırda kalır. Örnek girdi:
{"operation": "places", "items": [{"parent": "TR"}, {"parent": "TR-14"}]}Ne kadar tutar
- Anahtarsız: IPv4 adresi ya da IPv6 /64 başına UTC gününde 1.000 istek ücretsiz; bu hak bütün anahtarsız uç noktalarda (meta, countries, countries/{cc}, places, places/{id}, phone) ortaktır.
- Apify Actor, liste (places işlemi): döndürülen her 1.000 satır için 0,10 $.
- Apify Actor, tek yer ayrıntısı (place işlemi): 1.000 sorgu için 0,10 $.
Apify'da kullandıkça ödersiniz: yalnız yanıtlanan sorgular ücretlenir, isteğe dönüşemeyen öğeler ücretsizdir, her çalıştırmaya ayrıca 0,001 $ başlangıç ücreti eklenir. Apify'ın ücretsiz planındaki aylık 5 $ kredi yaklaşık 16.000 koordinat sorgusuna yeter. Doğrudan API anahtarı için api@forlab.io adresine yazın.
Sık sorulan sorular
Mahalle listesi eksiksiz mi?
Evet. Mahalle ve köyler TÜİK'in resmî listesinden gelir: 81 ilin, 973 ilçenin ve yaklaşık 50.000 mahalle ile köyün tamamı var. Yanıttaki meta.coverage.neighborhood: "partial" listeyi değil sınırları anlatır; mahallelerin yalnız bir kısmının harita sınırı var.
Köyler de listede mi?
Evet. Köyler mahallelerle aynı düzeyde, ilçenin altında gelir ve local_type alanı köy der. Belde ayrı bir düzey değildir; mahalle ya da köyün ayrıntısında (/v1/places/{id}) bir alan olarak gelir.
Kimlikler değişir mi?
Hayır. İller ISO kodunu taşır, diğer birimlerin kimliği kalıcıdır. Bir birim kaldırılırsa kimliği başka bir yere verilmez; sorgu PLACE_RETIRED kodunu ve yerine geçen kimliği (replaced_by) döndürür.
Ücretsiz kullanabilir miyim?
Liste ve arama anahtarsız çalışır: IPv4 adresi ya da IPv6 /64 başına UTC gününde 1.000 istek ücretsiz; bu hak bütün anahtarsız uç noktalarda (meta, countries, countries/{cc}, places, places/{id}, phone) ortaktır. Daha fazlası için Apify'daki Geo Reference Actor'ünü kullanın ya da api@forlab.io adresinden anahtar isteyin.