Türkiye API

Türkiye'nin illeri, ilçeleri, mahalleleri ve köyleri (ve kasabalar) hakkında bilgi içeren bir 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 Neler?

Son güncelleme: 9 Kasım 2024

İllere ve ilçelere posta kodları eklendi. (Deneysel özellik)
Filtreleme sistemi iyileştirildi.
- minArea ve maxArea gibi yeni sorgu parametreleri eklendi.
- Tüm ilçeleri getiren rotada il adına veya ID'sine göre filtreleme yapabilirsiniz.
- Tüm mahalleleri, köyleri ve kasabaları getiren rotalarda il/ilçe adına veya ID'sine göre filtreleme yapabilirsiniz.

Kaynaklar

Dokümantasyon

Son Düşünceler

V1 versiyonu artık geliştirme ve sürdürülebilirlik açısından sınırlara ulaşmış gibi görünüyor. 2022 yılında projeyi geliştirmeye başladığımda (üniversitedeki ilk yılıma yeni başlamıştım) proje ve repo adı "Türkiye İlleri API" idi. İlk aylarda API yalnızca il bilgilerini döndürüyordu (Bu bilgiler yalnızca beş özellikten oluşuyordu: id, isim, nüfus, alan kodu ve büyükşehir durumu). Zamanla API'deki hataları düzeltmeye ve yeni özellikler eklemeye odaklandım (bunlardan biri ilçelerdi). Zamanla ilçeler de il gibi kendi başına bir şema haline geldi fakat ayrı bir ID-Key bağlantısıyla yazılmak yerine ilgili illerin json dosyasındaki ilçe dizileri içinde yazıldı. Bu ilk sorundu, v1 için büyük ölçüde çözdüm, ama hâlâ bazı sorunlar var. İkinci sorun, başlangıçta sorgu parametreleri desteğinin olmamasıydı. Bu parametreler zamanla eklendi (önce "name, offset, limit", sonra filtreleme parametreleri, ardından fields ve en son olarak sort eklendi).

V1 kullanıcılarının API isteklerini bozmadan kodu sıfırdan yazmak kolay değil, ancak diğer projelere ve işlere de zaman ayırmak istiyorum. Bu yüzden bu projeye uzun bir ara veriyorum. Vakti geldiğinde muhtemelen v2 yazmaya başlayacağım. İncelemem gereken diğer örnek API'ler ve karar vermem gereken konular şunlar:

V2'de v1'den farklı olarak veritabanı kullanmalı mıyım?
Nasıl bir proje yapısı oluşturmalıyım?
camelCase yerine snake_case mi kullanmalıyım? (örneğin area_code yerine areaCode)
Nasıl bir rota yapısı kullanmalıyım? (İller, ilçeler vb. için ayrı rotalar yerine "/provinces/34/districts/1852" gibi rotalar mı?)
Şemalar arasında nasıl bir bağlantı olmalı? (İller > ilçeler > mahalleler + köyler sıralamasında belediyeleri nasıl konumlandırabiliriz?)
fields özelliği daha karmaşık (ya da daha fazla iç içe geçmiş) özellikleri ayarlayamıyor ve sort özelliği tüm alanlarda çalışmıyor. Buna nasıl bir çözüm bulabilirim?
Şu an aklıma gelmeyen daha pek çok şey.

Tüm bu sebeplerden dolayı, bu kez öğrenme ve iyi bir planlama açısından kendimi geliştirmeye çalışacağım. Proje, başladığı zamandan bu yana uzun bir yol kat etti ve çok daha gelişmiş özelliklere 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 zamana ihtiyacım var, bu yüzden uzun bir ara veriyorum. V2 çıktığında (eğer çıkarsa) daha iyi ve açıklayıcı bir dökümantasyona, daha sistematik ve genişletilebilir bir yapıya sahip olacak. Yine de önerilerinizi, isteklerinizi Türkiye API GitHub sayfasında issue açarak bildirebilirsiniz. Bu durumda bunları da v2 için değerlendireceğim.

En iyi dileklerimle!

API Kullanımı

İller

Tüm İlleri Getir

Endpoint: GET /api/v1/provinces

Bu rotayı kullanarak tüm illerin verilerine ulaşabilirsiniz. Kullanılabilir sorgu parametreleri:

name (string): Arama sorgunuzla eşleşen veya içeren tüm illeri gösterir.
minPopulation (number): Girilen değere eşit veya daha yüksek nüfusa sahip tüm illeri gösterir.
maxPopulation (number): Girilen değere eşit veya daha düşük nüfusa sahip tüm illeri gösterir.
minArea (number): Girilen değere eşit veya daha büyük alana sahip tüm illeri gösterir.
maxArea (number): Girilen değere eşit veya daha küçük alana sahip tüm illeri gösterir.
minAltitude (number): Girilen değere eşit veya daha yüksek rakıma sahip tüm illeri gösterir.
maxAltitude (number): Girilen değere eşit veya daha düşük rakıma sahip 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 bir başlangıç noktası belirlemenizi sağlar.
limit (number): Sayfalama için kullanılır. Gösterilecek maksimum sonuç sayısını belirler.
fields (string): Yanıtta görmek istediğiniz alanları gösterir.
sort (string): Sonuçları artan veya azalan sırada sıralar.

Belirli Bir İli Getir

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

Belirli bir ilin verilerine ulaşmak 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 Getir

Endpoint: GET /api/v1/districts

Bu rotayı kullanarak tüm ilçelerin verilerine ulaşabilirsiniz. Kullanılabilir sorgu parametreleri:

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

Belirli Bir İlçeyi Getir

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

Belirli bir ilçenin verilerine ulaşmak 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 Getir

Endpoint: GET /api/v1/neighborhoods

Bu rotayı kullanarak tüm mahallelerin verilerine ulaşabilirsiniz. Kullanılabilir sorgu parametreleri:

name (string): Arama sorgunuzla eşleşen veya içeren tüm mahalleleri gösterir.
minPopulation (number): Girilen değere eşit veya daha yüksek nüfusa sahip tüm mahalleleri gösterir.
maxPopulation (number): Girilen değere eşit veya daha düşük nüfusa sahip tüm mahalleleri gösterir.
provinceId (number): Girilen ID'ye sahip ildeki tüm mahalleleri gösterir.
province (string): Arama sorgunuzla eşleşen veya içeren ildeki tüm mahalleleri gösterir.
districtId (number): Girilen ID'ye sahip ilçedeki tüm mahalleleri gösterir.
district (string): Arama sorgunuzla eşleşen veya içeren ilçedeki tüm mahalleleri gösterir.
offset (number): Sayfalama için kullanılır. Arama sonuçlarında bir başlangıç noktası belirlemenizi sağlar.
limit (number): Sayfalama için kullanılır. Gösterilecek maksimum sonuç sayısını belirler.
fields (string): Yanıtta görmek istediğiniz alanları gösterir.
sort (string): Sonuçları artan veya azalan sırada sıralar.

Belirli Bir Mahalleyi Getir

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

Belirli bir mahallenin verilerine ulaşmak 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 Getir

Endpoint: GET /api/v1/villages

Bu rotayı kullanarak tüm köylerin verilerine ulaşabilirsiniz. Kullanılabilir sorgu parametreleri:

name (string): Arama sorgunuzla eşleşen veya içeren tüm köyleri gösterir.
minPopulation (number): Girilen değere eşit veya daha yüksek nüfusa sahip tüm köyleri gösterir.
maxPopulation (number): Girilen değere eşit veya daha düşük nüfusa sahip tüm köyleri gösterir.
provinceId (number): Girilen ID'ye sahip ildeki tüm köyleri gösterir.
province (string): Arama sorgunuzla eşleşen veya içeren ildeki tüm köyleri gösterir.
districtId (number): Girilen ID'ye sahip ilçedeki tüm köyleri gösterir.
district (string): Arama sorgunuzla eşleşen veya içeren ilçedeki tüm köyleri gösterir.
offset (number): Sayfalama için kullanılır. Arama sonuçlarında bir başlangıç noktası belirlemenizi sağlar.
limit (number): Sayfalama için kullanılır. Gösterilecek maksimum sonuç sayısını belirler.

Belirli Bir Köyü Getir

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

Belirli bir köyün verilerine ulaşmak 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:

TürkiyeAPI'nin v1 sürümünün (belediye birimleri olmadan) kapsamı iller, ilçeler, mahalleler ve köyleri içermektir. Ancak beldeler (bir tür belediye) ülkede önemli bir yere sahip olduğundan, mahalleler ve köyler gibi onlara iki rota ayrılmıştır. Kısacası, bu v1 için bir yama hazırlanmıştır. Bununla birlikte, mahalleler ve köyler gibi, beldeler /districts/:id rotasında gösterilmez, yani kendi içlerinde izole edilmişlerdir. Bununla birlikte, /towns ile başlayan bu rotalarda beldelerin bağlı olduğu il-ilçe adları ve ID'leri belirtilmiştir, yani isterseniz bunları kullanarak bağlantı kurabilirsiniz.
Bu sadece bir yama güncellemesidir (Issue #29). V2'de muhtemelen /towns rotasını kaldırıp yerine /municipalities rotasını ekleyeceğim.

Tüm Beldeleri Getir

Endpoint: GET /api/v1/towns

Bu rotayı kullanarak tüm beldelerin verilerine ulaşabilirsiniz. Kullanılabilir sorgu parametreleri:

name (string): Arama sorgunuzla eşleşen veya içeren tüm beldeleri gösterir.
minPopulation (number): Girilen değere eşit veya daha yüksek nüfusa sahip tüm beldeleri gösterir.
maxPopulation (number): Girilen değere eşit veya daha düşük nüfusa sahip tüm beldeleri gösterir.
provinceId (number): Girilen ID'ye sahip ildeki tüm beldeleri gösterir.
province (string): Arama sorgunuzla eşleşen veya içeren ildeki tüm beldeleri gösterir.
districtId (number): Girilen ID'ye sahip ilçedeki tüm beldeleri gösterir.
district (string): Arama sorgunuzla eşleşen veya içeren ilçedeki tüm beldeleri gösterir.
offset (number): Sayfalama için kullanılır. Arama sonuçlarında bir başlangıç noktası belirlemenizi sağlar.
limit (number): Sayfalama için kullanılır. Gösterilecek maksimum sonuç sayısını belirler.
fields (string): Yanıtta görmek istediğiniz alanları gösterir.
sort (string): Sonuçları artan veya azalan sırada sıralar.

Belirli Bir Beldeyi Getir

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

Belirli bir beldenin verilerine ulaşmak 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 eksik. Şu anda sadece iller ve ilçeler için bir posta kodu özelliği var ve mahalleler ve köyler için bir posta kodu özelliği daha sonra gelecek. Ancak bir diğer önemli nokta, posta kodu filtreleme yönteminin değiştirilebilmesi, başka bir yere taşınabilmesi ve mahalle ve köy posta kodları eklendikten sonra iller ve ilçeler için posta kodlarının kaldırılabilmesidir.

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

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

Posta Kodlarını Etkinleştir

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

Ardından, illeri ve ilçeleri posta koduna göre filtrelemek için aşağıdaki sorgu parametrelerini kullanabilirsiniz:

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

Posta kodları yalnızca rakamlardan oluşsa da, yine de bir string türüdür. Bunun nedeni, posta kodlarının sıfırla başlayabilmesidir.

Lisans

MIT

Katkıda Bulunma

Pull request'lerinizle katkıda bulunabilirsiniz. Önemli değişiklikler için önce tartışmak için bir issue açabilirsiniz.

Şablonlar

Index

İletişim

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

Destek

Beni desteklemek isterseniz bana bir kahve ısmarlayabilirsiniz. Buy me a coffee

ubeydeozdmr/turkiye-api-tr.md