Skip to content

Instantly share code, notes, and snippets.

@ubeydeozdmr

ubeydeozdmr/turkiye-api-tr.md

Last active July 22, 2026 07:51
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save ubeydeozdmr/e94ea5a1929805988b803ecb682c623a to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save ubeydeozdmr/e94ea5a1929805988b803ecb682c623a to your computer and use it in GitHub Desktop.
Download ZIP
Türkiye API (il, ilçe, mahalle, köy verileri)
Raw
turkiye-api-tr.md
TurkiyeAPI Logo

TurkiyeAPI

Türkiye idari bölümleri için hızlı, tip güvenli ve herkese açık REST API: iller, ilçeler, belediyeler, mahalleler ve köyler.

Dokümantasyon · API Referansı · OpenAPI · Metadata · Destek

API v2 Dataset 2025 Node.js >=22 <23 MIT License

Hızlı Başlangıç

curl "https://api.turkiyeapi.dev/v2/provinces"
curl "https://api.turkiyeapi.dev/v2/provinces?search=istanbul&fields=id,name,population"

TurkiyeAPI v2; 2025 veri setini bellekte tutulan JSON dosyalarından, tipli Fastify rotaları, TypeBox doğrulaması, OpenAPI dokümantasyonu, statik veri seti indirmeleri, sayfalama, filtreleme, alan projeksiyonu, açık ilişki include mekanizması, ETag, CORS ve oran sınırlama ile sunar.

TurkiyeAPI v2 mevcut stabil API sürümüdür. v1, mevcut kullanıcılar için legacy API olarak erişilebilir durumdadır.

İçindekiler

Türk idari bölümleri için hızlı REST API: iller, ilçeler, belediyeler, mahalleler ve köyler.

TurkiyeAPI v2; 2025 veri setini bellekte tutulan JSON dosyalarından, tipli Fastify rotaları, TypeBox doğrulaması, OpenAPI dokümantasyonu, statik veri seti indirmeleri, sayfalama, filtreleme, alan projeksiyonu, açık ilişki include mekanizması, ETag, CORS ve oran sınırlama ile sunar.

TurkiyeAPI bağımsız bir açık API projesidir. Herhangi bir resmî kurumla bağlantılı değildir, onaylanmamaktadır ve kurumlar tarafından işletilmemektedir.

Üretim Ortamı

  • API: https://api.turkiyeapi.dev
  • OpenAPI JSON: https://api.turkiyeapi.dev/v2/openapi.json
  • Yerel geliştirme: http://localhost:3000
  • Dokümantasyon (Türkçe): https://docs.turkiyeapi.dev/tr/v2/guide/
  • Dokümantasyon (İngilizce): https://docs.turkiyeapi.dev/en/v2/guide/
  • API Referansı (Türkçe): https://docs.turkiyeapi.dev/tr/v2/api-reference/
  • API Referansı (İngilizce): https://docs.turkiyeapi.dev/en/v2/api-reference/
  • Gizlilik Politikası: PRIVACY.md
  • Kullanım Şartları: TERMS.md

Veri

Güncel veri seti metadata bilgisi GET /v2/meta uç noktasında sunulur.

Kaynak Adet
İller 81
İlçeler 973
Belediyeler 1,377
Mahalleler 32,254
Köyler 18,183

Veri seti sürümü: 2025

Son güncelleme: 2026-05-21

Kaynaklar:

  • TÜİK MEDAS
  • PTT Kargo posta kodu verileri
  • T.C. MSB Harita Genel Müdürlüğü yüzölçümü verileri
  • Türk Telekom telefon alan kodu verileri
  • OpenStreetMap admin_centre koordinatları

Gereksinimler

  • Node.js >=22 <23
  • npm

Kurulum

npm install

Geliştirme

npm run dev

Sunucu varsayılan olarak 0.0.0.0:3000 üzerinde dinler. Port ve host değerlerini değiştirebilirsiniz:

PORT=4000 HOST=127.0.0.1 npm run dev

Derleme ve Çalıştırma

npm run build
npm start

Testler

npm test
npm run typecheck

Docker

docker build -t turkiye-api .
docker run --rm -p 3000:3000 turkiye-api

İmaj 3000 portunu açar ve /health için bir health check içerir.

Loglama

Üretimde loglama reverse proxy ile uygulama arasında ayrılmıştır. Caddy; trafik, TLS, yönlendirme, istemci IP, user-agent, referer, istek boyutu ve yanıt boyutu gibi ham erişim loglarını sahiplenmelidir. Fastify uygulaması varsayılan olarak sağlık kontrolleri dışındaki her istek için kompakt bir anlamsal log üretir.

Fastify istek logları requestId, version, method, path, route, queryKeys, statusCode, responseTimeMs, cacheStatus, rateLimit alanlarını ve uygun durumlarda yapılandırılmış hata alanlarını içerir. Sorgu parametresi değerleri, istek gövdeleri, yanıt gövdeleri, çerezler, authorization başlıkları ve API anahtarları uygulama loglarına yazılmaz.

Çalışma zamanı kontrolleri:

Değişken Varsayılan Açıklama
LOG_ENABLED true Fastify loglarını kapatmak için false yapın
LOG_LEVEL üretimde info Pino log seviyesi
LOG_HEALTHCHECKS false /health loglarını dahil etmek için true yapın
SERVICE_NAME turkiye-api-v2 Logger temel alanlarına eklenen servis adı
TRUST_PROXY yalnızca üretimde true Caddy arkasında çalışırken proxy IP başlıklarına güvenilirlik

API Genel Bakış

Sistem

Metot Yol Açıklama
GET /health Sağlık kontrolü
GET /v2/meta API ve veri seti metadata
GET /v2/openapi.json OpenAPI 3.1 dokümanı

Dinamik Kaynaklar

Metot Yol Açıklama
GET /v2/provinces İlleri listele
GET /v2/provinces/{provinceId} İl detayı getir
GET /v2/provinces/{provinceId}/districts Bir ildeki ilçeleri listele
GET /v2/provinces/{provinceId}/municipalities Bir ildeki belediyeleri listele
GET /v2/provinces/{provinceId}/neighborhoods Bir ildeki mahalleleri listele
GET /v2/provinces/{provinceId}/villages Bir ildeki köyleri listele
GET /v2/districts İlçeleri listele
GET /v2/districts/{districtId} İlçe detayı getir
GET /v2/districts/{districtId}/municipalities Bir ilçedeki belediyeleri listele
GET /v2/districts/{districtId}/neighborhoods Bir ilçedeki mahalleleri listele
GET /v2/districts/{districtId}/villages Bir ilçedeki köyleri listele
GET /v2/municipalities Belediyeleri listele
GET /v2/municipalities/{municipalityId} Belediye detayı getir
GET /v2/municipalities/{municipalityId}/neighborhoods Bir belediyedeki mahalleleri listele
GET /v2/neighborhoods Mahalleleri listele
GET /v2/neighborhoods/{neighborhoodId} Mahalle detayı getir
GET /v2/villages Köyleri listele
GET /v2/villages/{villageId} Köy detayı getir

Statik Veri Seti İndirmeleri

Güncel veri seti dosyaları:

GET /v2/datasets/provinces.json
GET /v2/datasets/districts.json
GET /v2/datasets/municipalities.json
GET /v2/datasets/neighborhoods.json
GET /v2/datasets/villages.json

Sürümlenmiş veri seti dosyaları:

GET /v2/datasets/2025/provinces.json
GET /v2/datasets/2025/districts.json
GET /v2/datasets/2025/municipalities.json
GET /v2/datasets/2025/neighborhoods.json
GET /v2/datasets/2025/villages.json

Örnekler

İlleri listele:

curl "https://api.turkiyeapi.dev/v2/provinces"

Arama yap ve alan projekte et:

curl "https://api.turkiyeapi.dev/v2/provinces?search=istanbul&fields=id,name,population"

İli ilişkili ilçelerle getir:

curl "https://api.turkiyeapi.dev/v2/provinces/34?fields=id,name&include=districts"

Bir ildeki belediyeleri listele:

curl "https://api.turkiyeapi.dev/v2/municipalities?provinceId=34&limit=25"

Belde belediyelerini listele:

curl "https://api.turkiyeapi.dev/v2/municipalities?type=town"

Statik veri seti indir:

curl "https://api.turkiyeapi.dev/v2/datasets/2025/provinces.json"

Yanıt Yapısı

Liste uç noktaları bir data dizisi ve sayfalama metadata alanı döner:

{
  "data": [
    {
      "id": 34,
      "name": "İstanbul"
    }
  ],
  "meta": {
    "count": 1,
    "total": 81,
    "limit": 1,
    "offset": 0,
    "datasetVersion": "2025",
    "lastUpdated": "2026-05-21"
  }
}

Detay uç noktaları tek bir data nesnesi döner:

{
  "data": {
    "id": 34,
    "name": "İstanbul"
  },
  "meta": {
    "datasetVersion": "2025",
    "lastUpdated": "2026-05-21"
  }
}

Metadata için basit bir veri zarfı kullanılır:

{
  "data": {
    "apiVersion": "2.0.0",
    "datasetVersion": "2025",
    "lastUpdated": "2026-05-21"
  }
}

Hata yanıtları yapılandırılmıştır:

{
  "error": {
    "code": "PROVINCE_NOT_FOUND",
    "message": "Province not found.",
    "status": 404
  }
}

Sorgu Parametreleri

Ortak liste parametreleri:

Parametre Açıklama
search Ada göre büyük/küçük harf duyarsız normalize metin araması
fields Virgülle ayrılmış alan projeksiyonu
sort id, -id, name, -name, population veya -population
limit Sayfa boyutu, 1 ile 1000 arası; varsayılan 100
offset Sıfır tabanlı ofset; varsayılan 0
minPopulation Minimum nüfus
maxPopulation Maksimum nüfus

Kaynağa özel filtreler:

Kaynak Filtreler
İller minArea, maxArea, minAltitude, maxAltitude, isCoastal, isMetropolitan
İlçeler provinceId, minArea, maxArea
Belediyeler provinceId, districtId, type
Mahalleler provinceId, districtId, municipalityId, postalCode, postalCodePrefix
Köyler provinceId, districtId, postalCode, postalCodePrefix

Boolean filtreler true veya false alır. Belediye type parametresi province_center, district_center veya town olabilir.

minPopulation değerinin maxPopulation değerinden büyük olması gibi çelişkili aralık filtreleri 400 INVALID_RANGE_FILTER döndürür. districtId değerinin verilen provinceId altında yer almaması gibi çelişkili hiyerarşi filtreleri 400 INVALID_HIERARCHY_FILTER döndürür.

Alan Projeksiyonu

Payload boyutunu azaltmak için fields kullanın:

GET /v2/provinces?fields=id,name,population
GET /v2/neighborhoods?fields=id,name,postalCode&limit=10

Bilinmeyen alanlar 400 INVALID_FIELDS döndürür.

Includes

Detay uç noktaları varsayılan olarak sığ yanıt döner. İlişkileri açıkça genişletmek için include kullanın.

Uç Nokta Desteklenen include değerleri
/v2/provinces/{provinceId} districts, municipalities, neighborhoods, villages
/v2/districts/{districtId} province, municipalities, neighborhoods, villages
/v2/municipalities/{municipalityId} province, district, neighborhoods
/v2/neighborhoods/{neighborhoodId} province, district, municipality
/v2/villages/{villageId} province, district

Bilinmeyen include değerleri 400 INVALID_INCLUDE döndürür.

Posta Kodu Durum Mantığı

Posta kodları, her değerin nasıl belirlendiğini açıklamak için postalCodeStatus alanı ile sunulur.

  • official: Posta kodu resmi PTT posta kodu verilerinde bulunur ve doğrudan bu kaynaktan kullanılır.
  • derived: Mevcut mahalle için PTT verilerinde posta kodu yoktur; ancak mahalle daha önce posta kodu bilinen bir köyün veya başka bir yerleşimin parçasıdır (ve bu bilgi PTT verilerinde vardır). Bu durumda önceki yerleşimin posta kodu kullanılır. Bu durum yalnızca mahalleler için kullanılır.
  • estimated: Posta kodu PTT verilerinde yoktur ve önceki yerleşimden türetilememiştir. Değer; ek kamu kaynakları, yakın yerleşimler, ilçe düzeyi posta kodu desenleri veya belgelenmiş idari değişikliklerden çıkarımla belirlenir. Tahmini değerler arama deneyimini iyileştirmek içindir; resmi PTT kaydı olarak değerlendirilmemelidir.

Resmî posta kodu verisinin kritik olduğu istemciler postalCodeStatus alanını kontrol etmelidir. Sadece resmi kayıtlar için postalCodeStatus=official filtrelemesi yapılmalıdır.

Mahalleler: 32,142 resmi, 76 türetilmiş, 36 tahmini, toplam 32,254

Köyler: 18,162 resmi, 21 tahmini, toplam 18,183

Önbellekleme

Dinamik /v2/* API yanıtları şunları içerir:

Cache-Control: public, max-age=300
ETag: ...

Güncel statik veri seti indirmeleri şunları içerir:

Cache-Control: public, max-age=3600, stale-while-revalidate=86400
ETag: ...
Last-Modified: ...

Sürümlenmiş statik veri seti indirmeleri şunları içerir:

Cache-Control: public, max-age=31536000, immutable
ETag: ...
Last-Modified: ...

If-None-Match başlığı eşleşen istekler 304 Not Modified alır.

Oran Sınırlama

Varsayılan oran sınırlama politikaları:

  • Dakikada 300 istek
  • 5 dakikada 1,000 istek

Kimlik çözümleme sırası x-api-key, ardından authorization, ardından istemci IP şeklindedir. Oran sınırlama başlıkları CORS üzerinden açığa çıkarılır:

x-ratelimit-limit
x-ratelimit-remaining
x-ratelimit-reset
retry-after

Gizlilik ve Şartlar

TurkiyeAPI uygulama loglarını bilinçli olarak minimal tutar. Uygulama logları; istek kimliği, API sürümü, metot, yol, rota, sorgu parametre adı listesi, durum kodu, yanıt süresi, önbellek durumu ve oran sınırlama özeti gibi operasyonel metadata içerir. İstek gövdeleri, yanıt gövdeleri, çerezler, authorization başlıkları, API anahtarları veya tam sorgu parametre değerleri dahil edilmez.

Üretim sunucusu ya da reverse-proxy erişim logları; güvenlik, kötüye kullanım önleme, oran sınırlama uygulaması ve operasyonel hata ayıklama amaçlarıyla IP adresi, user-agent, istek yolu/URI, zaman damgası, durum kodu, yanıt boyutu ve yanıt süresi gibi alanları içerebilir.

Gizlilik politikası için PRIVACY.md, kabul edilebilir kullanım şartları için TERMS.md dosyalarına bakın.

Proje Yapısı

src/
  app.ts                  Fastify uygulama oluşturucu
  server.ts               Çalışma zamanı giriş noktası
  data/                   Veri seti yükleme ve metadata
  indexes/                Bellek içi ilişki indeksleri
  routes/                 HTTP rota modülleri
  schemas/                TypeBox şemaları
  services/               Sorgu ve lookup servisleri
  utils/                  Yanıt, sayfalama, fields, includes, errors
datasets/                 Güncel ve sürümlenmiş JSON veri setleri
tests/                    Node test çalıştırıcı testleri

Ek Dokümantasyon

Katkı

Katkılar memnuniyetle karşılanır. Pull request açmadan önce CONTRIBUTING.md dosyasını okuyun ve şunları çalıştırın:

npm run format:check
npm run typecheck
npm test
npm run build

Güvenlik

Lütfen güvenlik sorunlarını herkese açık issue'larda paylaşmayın. Desteklenen sürümler ve sorumlu güvenlik bildirimi talimatları için SECURITY.md dosyasına bakın.

Destek

TurkiyeAPI ücretsiz ve herkese açıktır. Proje işinize yarıyorsa, .github/FUNDING.yml içinde tanımlı GitHub sponsor düğmesi üzerinden barındırma ve bakım süreçlerine destek olabilirsiniz.

Lisans

MIT

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment