Türkiye API

Türkiye'nin illeri, ilçeleri, mahalleleri ve köyleri (ve beldeleri) hakkında bilgi içeren API.

Alan adları

API ana alan adı olarak turkiyeapi.dev kullanır. Ancak aşağıdaki alan adlarını da kullanabilirsiniz:

turkiyeapi.herokuapp.com

Yenilikler

Son güncelleme: 3 Ağustos 2025

Yeni dokümantasyon docs.turkiyeapi.dev adresinde mevcuttur.
API dokümantasyonu artık hem İngilizce hem de Türkçe dillerinde mevcuttur.

Kaynaklar

Dokümantasyon

Son Değerlendirmeler

v1 sürümü geliştirilebilirlik ve sürdürülebilirlik açısından zorlanmaya başlamış gibi görünüyor. Projeyi ilk geliştirmeye başladığım 2022 yılında (o zamanlar üniversite birinci sınıfıma yeni başlamıştım), projenin adı (ve tabii ki reponun da) "Provinces of Turkey API" idi. Bunun nedeni, API ilk geliştirildiği ilk birkaç ay boyunca, sadece il bilgilerini alabilmenizdi (Ayrıca bu bilgiler sadece beş özellikten oluşuyordu: id, name, population, areaCode ve isMetropolitan). Zamanla API'nin hatalarını düzeltmeye ve yeni özellikler eklemeye odaklandım (bunlardan biri ilçelerdi). Zamanla ilçeler, iller gibi kendi başına bir şema haline geldi, ancak ID-Anahtar bağlantısıyla ayrı ayrı yazılmak yerine, bu ilçeler aynı json dosyasında ilgili illerin ilçe dizilerinde yazıldı. Bu birinci problemdir, v1 için bu problemi büyük ölçüde çözdüm, ancak hala bazı problemler var. İkinci problem, başlangıçta sorgu parametresi desteğinin olmamasıydı. Bu parametreler zamanla adım adım eklendi (önce "name, offset, limit" eklendi, sonra filtreleme parametreleri, sonra fields, son olarak sort).

v1 kullanıcılarının API isteklerini bozmadan kodu sıfırdan yazmak kolay değil, ancak diğer projeler ve diğer işler için zaman ayırmak istiyorum. Bu yüzden bu proje için uzun bir ara veriyorum. Zamanı geldiğinde, büyük olasılıkla v2 yazmaya başlayacağım. Diğer örnek API'leri incelemem ve ayrıca karar vermem gereken şeyler:

v1'in aksine v2'de veritabanı kullanmalı mıyım?
Ne tür bir proje yapısı oluşturmalıyım?
camelCase yerine snake_case tercih etmeli miyim? (areaCode yerine area_code gibi)
Ne tür bir rota yapısı kullanmalıyım? (iller, ilçeler vb. için ayrı rotalar yerine "/provinces/34/districts/1852" gibi rotalar kullanmalı mıyım?)
Şemalar arasında ne tür bir bağlantı olmalı? (iller > ilçeler > mahalleler + köyler gibi bir sıra olduğunda belediyeleri tam olarak nasıl konumlandırabiliriz)
fields özelliği ikinci dereceden (veya daha fazla iç içe geçmiş) özellikleri ayarlayamaz, ayrıca sort özelliği tüm alanlar için çalışmaz. Buna nasıl çözüm bulabilirim?
Şu anda aklıma gelmeyen daha birçok şey.

Tüm bunlar nedeniyle, bu sefer öğrenme açısından kendimi geliştirmeye çalışacağım ve bu sefer iyi planlayacağım. Proje ilk başladığı zamandan bu yana uzun bir yol kat etti ve çok daha gelişmiş yeteneklere sahip. Açıkçası, v2'ye kadar yetecek kadar özellik eklediğimi ve iyileştirmeler yaptığımı düşünüyorum. v2 için planladığım şeyleri gerçekleştirmek için biraz zamana ihtiyacım var, bu yüzden uzun bir ara veriyorum. v2 yayınlandığında (eğer yayınlanırsa) daha iyi ve daha açıklayıcı dokümantasyona sahip olacak, daha sistematik ve genişletilebilir olacak. Yine de Türkiye API GitHub sayfasında bir konu açarak önerilerinizi, isteklerinizi vb. gönderebilirsiniz. Bu durumda bunları v2 için de değerlendireceğim.

En iyi dileklerimle!

API Kullanımı

İller

Tüm İlleri Al

Endpoint: GET /api/v1/provinces

Tüm iller için veri almak için bu rotayı kullanabilirsiniz. Kullanılabilir sorgu parametreleri:

name (string): Arama sorgunuzu içeren veya eşleşen tüm illeri gösterir.
minPopulation (number): Girdiğiniz değerden büyük veya eşit nüfusa sahip tüm illeri gösterir.
maxPopulation (number): Girdiğiniz değerden küçük veya eşit nüfusa sahip tüm illeri gösterir.
minArea (number): Girdiğiniz değerden büyük veya eşit alana sahip tüm illeri gösterir.
maxArea (number): Girdiğiniz değerden küçük veya eşit alana sahip tüm illeri gösterir.
minAltitude (number): Girdiğiniz değerden büyük veya eşit yüksekliğe sahip tüm illeri gösterir.
maxAltitude (number): Girdiğiniz değerden küçük veya eşit yüksekliğe sahip tüm illeri gösterir.
isCoastal (boolean): Kıyı şehri olan veya olmayan tüm illeri gösterir.
isMetropolitan (boolean): Büyükşehir olan veya olmayan tüm illeri gösterir.
offset (number): Sayfalama için kullanılır. Arama sonuçlarında başlangıç noktası belirlemek için bunu kullanın.
limit (number): Sayfalama için kullanılır. Size gösterilecek maksimum sonuç sayısını belirlemek için bunu kullanın.
fields (string): Yanıtta görmek istediğiniz alanları gösterir.
sort (string): Sonuçları artan veya azalan düzende sıralar.

Belirli İl Al

Endpoint: GET /api/v1/provinces/:id

Belirli bir il için veri almak için bu rotayı kullanabilirsiniz. Kullanılabilir yol değişkenleri ve sorgu parametreleri:

id (Yol Değişkeni): İl ID'si
fields (Sorgu Parametresi, string): Yanıtta görmek istediğiniz alanları gösterir.
extend (Sorgu Parametresi, boolean): İlin genişletilmiş verilerini (mahalleler ve köyler) gösterir. [Varsayılan: false] (Bu deneysel bir özelliktir. Düzgün çalışmayabilir.)

İlçeler

Tüm İlçeleri Al

Endpoint: GET /api/v1/districts

Tüm ilçeler için veri almak için bu rotayı kullanabilirsiniz. Kullanılabilir sorgu parametreleri:

name (string): Arama sorgunuzu içeren veya eşleşen tüm ilçeleri gösterir.
minPopulation (number): Girdiğiniz değerden büyük veya eşit nüfusa sahip tüm ilçeleri gösterir.
maxPopulation (number): Girdiğiniz değerden küçük veya eşit nüfusa sahip tüm ilçeleri gösterir.
minArea (number): Girdiğiniz değerden büyük veya eşit alana sahip tüm ilçeleri gösterir.
maxArea (number): Girdiğiniz değerden küçük veya eşit alana sahip tüm ilçeleri gösterir.
provinceId (number): Girdiğiniz ID'ye sahip ildeki tüm ilçeleri gösterir.
province (string): Arama sorgunuzu içeren veya eşleşen ildeki tüm ilçeleri gösterir.
offset (number): Sayfalama için kullanılır. Arama sonuçlarında başlangıç noktası belirlemek için bunu kullanın.
limit (number): Sayfalama için kullanılır. Size gösterilecek maksimum sonuç sayısını belirlemek için bunu kullanın.
fields (string): Yanıtta görmek istediğiniz alanları gösterir.
sort (string): Sonuçları artan veya azalan düzende sıralar.

Belirli İlçe Al

Endpoint: GET /api/v1/districts/:id

Belirli bir ilçe için veri almak için bu rotayı kullanabilirsiniz. Kullanılabilir yol değişkenleri ve sorgu parametreleri:

id (Yol Değişkeni): İlçe ID'si
fields (Sorgu Parametresi, string): Yanıtta görmek istediğiniz alanları gösterir.

Mahalleler

Tüm Mahalleleri Al

Endpoint: GET /api/v1/neighborhoods

Tüm mahalleler için veri almak için bu rotayı kullanabilirsiniz. Kullanılabilir sorgu parametreleri:

name (string): Arama sorgunuzu içeren veya eşleşen tüm mahalleleri gösterir.
minPopulation (number): Girdiğiniz değerden büyük veya eşit nüfusa sahip tüm mahalleleri gösterir.
maxPopulation (number): Girdiğiniz değerden küçük veya eşit nüfusa sahip tüm mahalleleri gösterir.
provinceId (number): Girdiğiniz ID'ye sahip ildeki tüm mahalleleri gösterir.
province (string): Arama sorgunuzu içeren veya eşleşen ildeki tüm mahalleleri gösterir.
districtId (number): Girdiğiniz ID'ye sahip ilçedeki tüm mahalleleri gösterir.
district (string): Arama sorgunuzu içeren veya eşleşen ilçedeki tüm mahalleleri gösterir.
offset (number): Sayfalama için kullanılır. Arama sonuçlarında başlangıç noktası belirlemek için bunu kullanın.
limit (number): Sayfalama için kullanılır. Size gösterilecek maksimum sonuç sayısını belirlemek için bunu kullanın.
fields (string): Yanıtta görmek istediğiniz alanları gösterir.
sort (string): Sonuçları artan veya azalan düzende sıralar.

Belirli Mahalle Al

Endpoint: GET /api/v1/neighborhoods/:id

Belirli bir mahalle için veri almak için bu rotayı kullanabilirsiniz. Kullanılabilir yol değişkenleri ve sorgu parametreleri:

id (Yol Değişkeni): Mahalle ID'si
fields (Sorgu Parametresi, string): Yanıtta görmek istediğiniz alanları gösterir.

Köyler

Tüm Köyleri Al

Endpoint: GET /api/v1/villages

Tüm köyler için veri almak için bu rotayı kullanabilirsiniz. Kullanılabilir sorgu parametreleri:

name (string): Arama sorgunuzu içeren veya eşleşen tüm köyleri gösterir.
minPopulation (number): Girdiğiniz değerden büyük veya eşit nüfusa sahip tüm köyleri gösterir.
maxPopulation (number): Girdiğiniz değerden küçük veya eşit nüfusa sahip tüm köyleri gösterir.
provinceId (number): Girdiğiniz ID'ye sahip ildeki tüm köyleri gösterir.
province (string): Arama sorgunuzu içeren veya eşleşen ildeki tüm köyleri gösterir.
districtId (number): Girdiğiniz ID'ye sahip ilçedeki tüm köyleri gösterir.
district (string): Arama sorgunuzu içeren veya eşleşen ilçedeki tüm köyleri gösterir.
offset (number): Sayfalama için kullanılır. Arama sonuçlarında başlangıç noktası belirlemek için bunu kullanın.
limit (number): Sayfalama için kullanılır. Size gösterilecek maksimum sonuç sayısını belirlemek için bunu kullanın.
fields (string): Yanıtta görmek istediğiniz alanları gösterir.
sort (string): Sonuçları artan veya azalan düzende sıralar.

Belirli Köy Al

Endpoint: GET /api/v1/villages/:id

Belirli bir köy için veri almak için bu rotayı kullanabilirsiniz. Kullanılabilir yol değişkenleri ve sorgu parametreleri:

id (Yol Değişkeni): Köy ID'si
fields (Sorgu Parametresi, string): Yanıtta görmek istediğiniz alanları gösterir.

Beldeler

Önemli Notlar:

TurkiyeAPI'nin v1 sürümünün kapsamı (belediye birimleri olmadan) iller, ilçeler, mahalleler ve köyleri içermektir. Ancak beldeler (bir belediye türü) ülkede önemli bir yere sahip olduğu için, mahalleler ve köyler gibi onlara da iki rota tahsis edildi. Kısacası, bu v1 için hazırlanmış bir yamadır. Ancak mahalle ve köylerin aksine, /districts/:id rotasında gösterilmezler, yani kendi içlerinde izole edilmişlerdir. Bununla birlikte, /towns ile başlayan bu rotalarda, beldelerin bağlı olduğu il-ilçe isimleri ve ID'leri belirtilir, yani isterseniz bunları kullanarak bağlantı kurabilirsiniz.
Bu sadece bir yama güncellemesidir (#29 sorununu kontrol edin), sürüm 2'de muhtemelen /towns rotasını kaldıracağım ve bunun yerine /municipalities rotasını ekleyeceğim.

Tüm Beldeleri Al

Endpoint: GET /api/v1/towns

Tüm beldeler için veri almak için bu rotayı kullanabilirsiniz. Kullanılabilir sorgu parametreleri:

name (string): Arama sorgunuzu içeren veya eşleşen tüm beldeleri gösterir.
minPopulation (number): Girdiğiniz değerden büyük veya eşit nüfusa sahip tüm beldeleri gösterir.
maxPopulation (number): Girdiğiniz değerden küçük veya eşit nüfusa sahip tüm beldeleri gösterir.
provinceId (number): Girdiğiniz ID'ye sahip ildeki tüm beldeleri gösterir.
province (string): Arama sorgunuzu içeren veya eşleşen ildeki tüm beldeleri gösterir.
districtId (number): Girdiğiniz ID'ye sahip ilçedeki tüm beldeleri gösterir.
district (string): Arama sorgunuzu içeren veya eşleşen ilçedeki tüm beldeleri gösterir.
offset (number): Sayfalama için kullanılır. Arama sonuçlarında başlangıç noktası belirlemek için bunu kullanın.
limit (number): Sayfalama için kullanılır. Size gösterilecek maksimum sonuç sayısını belirlemek için bunu kullanın.
fields (string): Yanıtta görmek istediğiniz alanları gösterir.
sort (string): Sonuçları artan veya azalan düzende sıralar.

Belirli Belde Al

Endpoint: GET /api/v1/towns/:id

Belirli bir belde için veri almak için bu rotayı kullanabilirsiniz. Kullanılabilir yol değişkenleri ve sorgu parametreleri:

id (Yol Değişkeni): Belde ID'si
fields (Sorgu Parametresi, string): Yanıtta görmek istediğiniz alanları gösterir.

Posta Kodları Hakkında

Posta kodları özelliği şu anda kısmen eksiktir. Şu anda sadece iller ve ilçeler için posta kodu özelliği var, mahalle ve köyler için posta kodu özelliği daha sonra gelecek. Ancak diğer önemli bir nokta, mahalle & köy posta kodları eklendikten sonra posta kodu filtreleme yönteminin değiştirilebilir, başka bir yere taşınabilir ve iller ve ilçeler için posta kodları kaldırılabilir.

Bu rotalar için posta kodu özelliğini etkinleştirmek için aşağıdaki sorgu parametresini (true olarak ayarlamalısınız) kullanabilirsiniz: Tüm İlleri Al, Belirli İl Al, Tüm İlçeleri Al, Belirli İlçe Al.

Öncelikle "activatePostalCodes" sorgu parametresini true olarak ayarlayarak posta kodu özelliğini etkinleştirmelisiniz.

Posta Kodlarını Etkinleştir

activatePostalCodes (boolean): Posta kodu özelliğini etkinleştirir. [Varsayılan: false]

Daha sonra iller ve ilçeleri posta koduna göre filtrelemek için aşağıdaki sorgu parametrelerini kullanabilirsiniz:

postalCode (string): Arama sorgunuzu içeren veya eşleşen tüm il/ilçeleri gösterir.

Posta kodları sadece rakamlardan oluşmasına rağmen, yine de string türündedir. Bunun nedeni posta kodlarının sıfır ile başlayabilmesidir.

Lisans

MIT

Katkıda Bulunma

Pull request'ler memnuniyetle karşılanır. Büyük değişiklikler için, lütfen önce neyi değiştirmek istediğinizi tartışmak için bir konu açın.

Şablonlar

Ana Sayfa

İletişim

Benimle email veya Twitter üzerinden iletişime geçebilirsiniz.

Destek

Beni desteklemek istiyorsanız, bana bir kahve ısmarlayabilirsiniz. Buy me a coffee

ubeydeozdmr/turkiye-api-tr.md