Rehber

TurkiyeAPI v2, Türkiye'nin idari verileri için salt okunur bir REST API'dir. Bu rehber; veri modelini, kaynakların birbirleriyle ilişkisini ve endpoint'lerin gerçek kullanım akışlarında nasıl birleştirileceğini açıklar.

API'yi öğrenirken veya entegrasyon tasarlarken rehberi kullanın. Endpoint sözleşmeleri, alan listeleri, izin verilen sorgu değerleri ve hata kodları için API Referansı bölümüne bakın.

Ne Geliştirebilirsiniz?

API; adres formları, konum seçiciler, raporlama araçları, dashboard'lar, açık veri çalışmaları ve Türkiye idari birimlerine ihtiyaç duyan doğrulama akışları için kullanılabilir.

Yaygın kullanım akışları:

• İl -> ilçe -> mahalle adres formları geliştirmek.
• Seçilen bir ilin ilçelerini listelemek.
• Bir ilçe içindeki belediyeleri bulmak.
• Bir belediyeye bağlı mahalleleri yüklemek.
• Daha geniş kapsamda mahalle aramak.
• Yerleşimleri nüfusa göre filtrelemek.
• Tüm veri setini offline işleme için indirmek.

Rehber Bölümleri

Bölüm	Ne açıklar?
Başlarken	Base URL, v2 prefix'i, auth gerektirmeyen erişim, ilk istek ve yanıt yapısı
Kavramlar	İl, ilçe, belediye, mahalle, köy, ID'ler, slug'lar ve parent ID'ler
İdari Yapı	Türkiye idari hiyerarşisinin API'de nasıl temsil edildiği
Yaygın Kullanım Senaryoları	Seçiciler, arama ekranları, detay sayfaları ve bulk veri için hangi endpoint yaklaşımının kullanılacağı
Filtreleme, Sıralama ve Sayfalama	Liste endpoint'lerindeki ortak sorgu parametreleri ve örnekler
Veri Setleri	Canlı API endpoint'leri ile statik veri seti dosyalarının ne zaman kullanılacağı
Örnekler	İstanbul'un ilçeleri ve belediyeye göre mahalleler gibi gerçek kullanım akışları
v1'den v2'ye Geçiş	Mevcut entegrasyonlar için v1 ve v2 farkları
SSS	Erişim, metadata, veri setleri ve destek hakkında referans dışı yanıtlar
Destek	Proje sürdürülebilirliği için isteğe bağlı bağış ve sponsorluk notları
Gizlilik Politikası	Public API'nin neleri logladığı, logların neden kullanıldığı ve saklama süresi
Kullanım Şartları	Kabul edilebilir kullanım, rate limit'ler, garanti verilmemesi ve bağımsız proje durumu

API Yapısı

Tüm v2 yerleşim kaynakları aynı base URL altında bulunur:

https://api.turkiyeapi.dev/v2

API, JSON yanıt envelope yapıları kullanır:

• Liste endpoint'leri data dizisi ve sayfalama metadata'sı döndürür.
• Tekil kaynak endpoint'leri data objesi ve veri seti metadata'sı döndürür.
• Hatalar sabit bir kod, mesaj ve HTTP status içeren error objesi döndürür.

Resmi TypeScript İstemcisi

@turkiyeapi/client, TurkiyeAPI v2 için resmi ve hafif TypeScript istemcisidir. fetch kullandığı için modern tarayıcılarda ve Node.js 18+ üzerinde çalışır.

ÖNİZLEME

Bu paket şu anda pre-1.0.0 geliştirme aşamasındadır. Public API, v1.0.0 öncesinde değişebilir.

npm üzerinden kurabilirsiniz:

npm install @turkiyeapi/client

Temel kullanım:

import { TurkiyeAPI } from '@turkiyeapi/client';

const api = new TurkiyeAPI();

const provinces = await api.provinces.list({
  search: 'istanbul',
  fields: ['id', 'name', 'population'],
});

const istanbul = await api.provinces.get(34);
const districts = await api.provinces.districts(34, { limit: 50 });

Kaynak Haritası

Temel kaynaklar:

• provinces: Türkiye'nin 81 ili.
• districts: İllere bağlı ilçeler.
• municipalities: İllere ve ilçelere bağlı yerel yönetimler.
• neighborhoods: İl, ilçe ve belediyeye bağlı mahalle kayıtları.
• villages: İl ve ilçeye bağlı köy kayıtları.

Alanlar ve endpoint listeleri için API Referansı bölümüne bakın.