Genel Bakış
TurkishGeoAPI (TR Map SVG API), Türkiye'nin yönetimsel coğrafi yapılanmasını (İl, İlçe, Mahalle) sunan ve il bazında SVG map_path verileri dönerek frontend projelerinin dinamik Türkiye haritası oluşturmasını sağlayan RESTful servistir. İstemcilere performans odaklı cevap veren uç noktaları, akıllı caching yapısı ile donatılmıştır.
Yapılandırma & Kurallar
- Versiyon: v1.0.0
- Base URL Prefix: /api/v1
- Veritabanı Modeli: Tüm adres verileri İlişkisel Veritabanı yönetim modeli (RDBMS) üzerinde normalize edilerek saklanmıştır. Foreign Key mappingleri SQLAlchemy üzerinden sağlanır.
- İstek Limitlendirme (Rate Limiting): Tüm endpoint'ler SlowAPI tarafından "dakikada 60 istek" olacak şekilde sınırlandırılmıştır.
- Önbellekleme (Caching): İl, İlçe, Mahalle okuma ve map-svg istekleri için FastAPI-Cache kullanılarak In-Memory (RAM tabanlı) 24 Saatlik (86400 saniye) Cache işlemi yapılır. Search endpoint cache'i 1 saat (3600 sn) aralığındadır.
- Güvenlik ve CORS: API tüm alan adlarından (origins) erişime açıktır. Ancak izinsiz modifikasyonları önlemek amacıyla yalnızca güvenli HTTP metodu olan "GET" kabul edilir.
Endpoints
id bazlı ilgili ili, il'e ait SVG (svg_path) verisini ve iliin ilçelerini içeren zengin içerikli detayı döner.
| Name | Description |
|---|---|
| parameter string | İller Listesi: |
| parameter string | İl Detayı: |
{
"status": "success",
"data": {
"totalCount": 10,
"results": [
{
"id": "5f4d8...001",
"name": "..."
}
]
}
}
İlişkili mahalleleri ile birlikte seçili ilçe detaylarını id bazlı döner.
| Name | Description |
|---|---|
| parameter string | İlçe Detayı: |
{
"status": "success",
"data": {
"totalCount": 10,
"results": [
{
"id": "5f4d8...001",
"name": "..."
}
]
}
}
81 ilin tüm listesini d_path (svg_path dizgilerini) değerleri ile beraber döner. Front-end geliştiriciler sadece bu endpoint üzerinden tüm haritayı çizmeyi sağlayacak vektör dataya topluca ulaşabilir.
| Name | Description |
|---|---|
| parameter string | SVG Path Koleksiyonu: |
{
"status": "success",
"data": {
"totalCount": 10,
"results": [
{
"id": "5f4d8...001",
"name": "..."
}
]
}
}
İl, ilçe ve mahalle tablolarında verileri string-like operasyonuyla arayarak { "provinces": [], "districts": [], "neighborhoods": [] } formatında eşleşen en benzeyen ilk 5 sonucu (limit: 5) kategorize ederek listeler. Hızlı tamamlama (Autocomplete) mimarileri için tasarlanmıştır.
| Name | Description |
|---|---|
| parameter string | Çoklu Tablo (Fuzzy) Arama: |
{
"status": "success",
"data": {
"totalCount": 10,
"results": [
{
"id": "5f4d8...001",
"name": "..."
}
]
}
}
Hata Kodları (Responses)
- 400 Bad Request: İsteğin formatı veya tip uyumsuzluğu (örn. ID yerine string geçilmesi).
- 404 Not Found: Çağrılan id veritabanı kayıtlarında bulunamazsa döner.
- 422 Unprocessable Entity: Zorunlu argüman eksiklikleri (örn. arama kelimesinin 3 karakterden kısa olması durumu).
- 429 Too Many Requests: Ziyaretçinin Rate Limit'i (60 req/min) doldurması durumunda tetiklenir.