Geo API: il, ilçe, mahalle ve koordinat API'si
Dünyadaki ülkeleri ve birinci düzey bölgelerini, Türkiye'nin il, ilçe ve mahallelerini tek bir API'de toplar. Bir koordinatın hangi ülke, il ve ilçede olduğunu, en yakın yerleşimleri ve saat dilimini söyler; posta kodlarını bulur, sınırları haritaya hazır GeoJSON olarak verir, telefon numaralarını doğrular ve biçimlendirir.
Canlı demo
Üstteki kutuda bir yer arayın, bir sekmede örneğe tıklayın ya da haritada bir nokta seçin. Sonuç sekmede, Geo API'ye giden istekler, yanıtları ve kodu haritanın altında görünür. Demo bizim sunucumuzda çalışır: IP başına saatte 300 sorgu.
— ülke— il— ilçeVeri sürümü —
Bir nokta hangi ülke, il, ilçe ve mahallede; en yakın yerleşimler hangileri, yerel saat kaç? Haritaya tıklayın ya da bir örnek seçin.
Bir yer seçmek için haritaya tıklayın ya da bir örnek seçin.
Adres formundaki ülke → il → ilçe → mahalle listeleri hazır gelir. Mahalle listesi kısmidir; her mahalle yok.
Bir yer seçmek için haritaya tıklayın ya da bir örnek seçin.
Bir ülkenin kodları, telefon kodu, para birimi, dili, saat dilimi ve idari düzeyleri.
Bir ülke seçin.
Bir noktanın saat dilimi, UTC farkı, yaz saati ve yerel saati. Haritaya tıklayın ya da bir örnek seçin.
Seçili yerin sınırı haritaya hazır GeoJSON olarak; bütün sınırlar da tek dosyadan vektör karo olarak.
Önce bir yer seçin ya da bir örneğe tıklayın.
Vektör karolar
Bütün sınırlar tek bir PMTiles dosyasında; anahtar istemez, tarayıcı yalnız baktığı parçayı indirir. Adres veri sürümünü taşır ve bir yıl önbelleklenir. Adresler /v1/meta yanıtında.
import maplibregl from "maplibre-gl";
import { Protocol } from "pmtiles";
maplibregl.addProtocol("pmtiles", new Protocol().tile);
new maplibregl.Map({
container: "map",
style: {
version: 8,
sources: { tr: { type: "vector", url: "pmtiles://https://…/TR.pmtiles" } },
layers: [{ id: "il", type: "line", source: "tr", "source-layer": "il" }],
},
});Numara geçerli mi, E.164 ve ulusal biçimi ne, hangi hat türü?
Numara + ile başlamıyorsa hangi ülkenin numarası olduğunu iki harfle yazın (TR, DE…).Kaydettiğiniz kimlik veri güncellenince bozulmaz; her hata sabit bir kodla gelir.
Kimlik biçimleri
- ülke: ISO 3166-1 kodu
- il: ISO 3166-2 kodu
- diğerleri: ülke kodu + 8 karakter (Kadıköy ilçesi)
Hata sözleşmesi
400 INVALID_REQUEST- Parametre eksik ya da biçimi yanlış.
401 UNAUTHORIZED- Anahtar yok ya da geçersiz.
404 NOT_FOUND- Bu kimlikte bir yer hiç olmadı.
404 BOUNDARY_UNAVAILABLE- Yer var ama sınırı yok.
410 PLACE_RETIRED- Kimlik emekli; replaced_by yenisini söyler.
429 RATE_LIMITED- Çok sık istek; biraz sonra tekrar deneyin.
503 NOT_READY- Veri henüz yüklenmedi.
Emekli kimlik örnek
Kaynak veride bir yer değişince eski kimlik silinmez: 410 PLACE_RETIRED ve replaced_by ile yenisi döner. Canlı veride henüz emekli kimlik yok; aşağıdaki yanıt gerçek bir değişikliğin (Mali, Bamako bölgesi) örneğidir.
GET /v1/places/ML-20 → 410
{ "status": "failed", "code": "PLACE_RETIRED", "replaced_by": "ML-BKO" }Kaynaklar ve lisanslar
Veri sürümü — · Her yanıtın meta alanında da yazar.
Bu harita yalnız Geo API'nin vektör karolarıyla çiziliyor; fareyle bir yerin üstüne gelince adı görünür.
API'ye giden istekler
Bir örnek seçin ya da haritaya tıklayın: sunucumuzun Geo API'ye gönderdiği her istek, durumu, süresi, yanıtı ve kodu burada görünür.
Süre, sunucumuzdan Geo API'ye ölçülen yanıt süresidir. Kod sunucuda çalışır: GEO_API_URL ve GEO_API_KEY sizin değerleriniz, anahtar tarayıcıya gelmez.
Geo API ile neler yapabilirsiniz
Türkiye il, ilçe ve mahalle verisi, dünya ülkeleri ve bölgeleri, sınırlar, yakın yerleşimler, saat dilimleri, posta kodları ve telefon numaraları tek bir sürümlü veri kaynağından gelir.
Koordinattan il ve ilçe bulma
Bir enlem ve boylam gönderin; noktayı içeren ülke ve bölge, Türkiye'de il ve ilçe gerçek sınırlarla bulunur (reverse geocoding). Nokta denizdeyse tahmin yürütülmez, boş yanıt döner.
En yakın yerleşimler
Bir koordinata en yakın şehir, kasaba ve köyleri mesafesi (km) ve nüfusuyla alın; her yerleşim bağlı olduğu ülke ve bölgeyle gelir. Kaynak GeoNames: dünyada 500'den fazla nüfuslu yerleşimler ve yönetim merkezleri.
Koordinattan saat dilimi ve yerel saat
Bir noktanın IANA saat dilimini (örneğin Europe/Istanbul), o anki UTC farkını, yaz saatinde olup olmadığını ve yerel saatini alın. Sınırların çakıştığı bölgelerde bütün adaylar listelenir; açık denizde tahmin yürütülmez.
250 ülke ve bağımlı bölge profili
Her ülke için ISO kodları, telefon kodları, para birimleri, diller, saat dilimleri ve idari düzeyleri, her düzeyin ne kadar kapsandığıyla birlikte gelir.
Adres formu için ülke, il, ilçe ve mahalle listeleri
Açılır listeleri tek uç noktadan doldurun: ülke → il → ilçe → mahalle. Türkiye'de 81 ilin, 973 ilçenin ve TÜİK'in resmî listesindeki yaklaşık 50.000 mahalle ile köyün tamamı var; veriler resmî ve açık kaynaklardan güncel tutulur. Dünyada 226 ülkede yaklaşık 3.900 birinci düzey bölge (eyalet, il) var.
Posta kodu sorgulama
Bir posta kodunun hangi yerlere ait olduğunu ve bir noktaya en yakın posta kodlarını bulun. Yaklaşık 120 ülke kapsanır (GeoNames, CC BY 4.0); Birleşik Krallık, Kanada ve Hollanda'da yalnız kodun ilk kısmı var. Türkiye'deki kodlar ilçesine bağlanır.
Nüfus bilgisi
Ülkeler, bölgeler, Türkiye'nin il ve ilçeleri ve yakın yerleşimler nüfusuyla gelir (GeoNames). Mahallelerin çoğunda nüfus bilgisi yok.
Yazarken yer arama
Adın ilk harfleriyle yer bulur; büyük/küçük harf, aksan ve ı/İ farkı yok sayılır. Arama bir ülkeyle sınırlanabilir, her aday üst birimleriyle gelir.
Yerin tam yolu
Bir kimlikle yerin adını, türünü, merkez koordinatını ve ülkeden başlayan üst birimlerini (path) alın: Kadıköy'deki bir mahallenin path'i Türkiye › İstanbul › Kadıköy'dür.
GeoJSON sınırlar
Ülke, il ya da ilçe sınırı tek bir GeoJSON Feature olarak gelir; MapLibre ve Leaflet'e doğrudan verilir. Üç ayrıntı düzeyi var: genel harita, şehir görünümü ve kaynak geometri.
Vektör harita karoları (PMTiles)
Dünyanın ülke ve bölge sınırları ile Türkiye'nin il, ilçe ve mahalle sınırları PMTiles dosyası olarak sunulur; harita anahtar istemeden çizilir.
Telefon numarası doğrulama
Numaranın geçerli olup olmadığını ve hat türünü (cep, sabit) söyler; E.164, ulusal ve uluslararası biçimde döner.
Çok dilli yer adları
Adlar yerel dilde gelir; lang parametresiyle (örneğin lang=en,de) başka dillerdeki adlar eklenir. Yer adları 600'ü aşkın dil etiketinde, ülke ve para birimi adları 300'den fazla dilde var. Kapsam dile göre değişir: Almanca, Fransızca, İngilizce, İspanyolca ve Türkçe gibi dillerde binlerce yer adı bulunur, olmayan ad boş (null) döner.
Kalıcı kimlikler
TR ve TR-34 gibi kimlikler veri güncellemelerinde korunur. Kaldırılan bir kimlik 410 ile yerine geçen kimliği (replaced_by) döner; kayıtlı verileriniz bozulmaz.
Sürümlü açık veri, OpenAPI ve sabit hata kodları
Her yanıt veri sürümünü ve atfı taşır; kaynaklar ve lisanslar /v1/meta'da. Sözleşmenin tamamı OpenAPI belgesinde, her hata sabit bir kodla gelir.
Milisaniyeler içinde yanıt
Veri sunucuda hazır durur; sorgular milisaniyeler içinde döner. Listeler veri sürümüne göre önbelleğe alınabilir.
3 adımda başla
- Anahtarı kendi sunucunuzda tutun; her /v1 çağrısı Authorization: Bearer başlığı ister. Anahtarı tarayıcıya koymayın.
- Bir GET isteği gönderin. Demodaki her işlem, gönderdiği isteği curl, Node ve Python kodu olarak verir.
- Yanıtı okuyun: {data, meta}. meta veri sürümünü ve atfı taşır; hatalar {status: "failed", code} döner. Listeleri veri sürümüne göre önbelleğe alın.
curl -H "Authorization: Bearer $GEO_API_KEY" "$GEO_API_URL/v1/contains?lat=41.0082&lon=28.9784"Bütün uç noktalar, parametreler ve yanıt şemaları OpenAPI belgesinde. · API referansı · openapi.json
Kullanım örnekleri
Her iş için ayrı bir sayfa: ne döndüğü, gerçek bir istek ve yanıt, fiyatı ve sık sorulanlar.