Genel Bakış
World Location API, uluslararası coğrafi modellemeyi "Ülkeler, Eyaletler/Bölgeler, Şehirler" (Countries, States, Cities) hiyerarşisi altında profesyonelce sunan açık kaynaklı bir RESTful servistir. İstemci projelerin uluslararası adres yönetimlerini asenkron CRUD işlemleri ve "Lazy Loading" mantığıyla ölçeklendirilebilir veritabanlarından çekmesine imkân verir.
Yapılandırma & Kurallar
- Versiyon: v1.0.0
- Base URL Prefix: /api/v1
- Veritabanı Modeli: Tüm Global Veriler (Küresel Lokasyonlar) İlişkisel Veritabanı yönetim modeli üzerinde normalize ve indexlenmiş şekilde tutulur. Model ilişkileri SQLAlchemy ORM ile yürütülür.
- İstek Limitlendirme (Rate Limiting): Tüm endpoint'ler API'yi olası DoS/DDoS ve Brute Force tarama saldırılarından korumak için "dakikada 60 istek" (60 req/min) olacak şekilde IP bazlı Rate Limiting ile sınırlandırılmıştır. Root endpoint (dakikada 10 istek).
- Önbellekleme (Caching): Tüm standart GET listeleri için uç noktalar 24 Saatlik (86400 saniye) In-Memory Cache (RAM) ile güçlendirilmişken, manipülatif Arama (Search) servisi 1 Saat (3600 sn) cache tutularak performans arşa çıkartılmıştır.
- Güvenlik ve Sahalar: API halka açıktır ve allow_origins=["*"] parametresiyle yapılandırılmıştır. İstismar olasılığı bulunmadığı için metot tipi sadece güvence altına alınmış "GET" isteklerine tanımlanmıştır.
Endpoints
ID si belirtilen eşsiz ülke objesini sunar.
| Name | Description |
|---|---|
| Liste query / Tüm Ülkeler | |
| skip query / int, default: 0 | Veritabanı okuma başlangıcı (offset). |
| limit query / int, default: 300, max: 500 | Veritabanı çekim hacmi (limit). |
| parameter string | Ülke Detayı: |
{
"status": "success",
"data": {
"totalCount": 10,
"results": [
{
"id": "5f4d8...001",
"name": "..."
}
]
}
}
ID si belirtilen eşsiz Eyalet objesini detaylarıyla döner.
| Name | Description |
|---|---|
| parameter string | Ülkeye Göre Eyaletler Listesi: |
| parameter string | Eyalet Detayı: |
{
"status": "success",
"data": {
"totalCount": 10,
"results": [
{
"id": "5f4d8...001",
"name": "..."
}
]
}
}
Özel bir state (Eyalet) kimliğine bağlı (örn. California vb.) tüm şehirleri Pagination ile listeler.
| Name | Description |
|---|---|
| parameter string | Eyalete Göre Şehirler Listesi: |
{
"status": "success",
"data": {
"totalCount": 10,
"results": [
{
"id": "5f4d8...001",
"name": "..."
}
]
}
}
ORM tabanlı metinsel Fuzzy sorgulama ile ilçe, eyalet ve ülkelere ait eşleşen ilk kayıtları çeker. Çıktı olarak {"countries": [], "states": [], "cities": []} obje dictionary döner. Front-end Search Bar entegrasyonları için çok kullanışlıdır.
| Name | Description |
|---|---|
| Küresel Çoklu-Tablo Araması query / Search_Locations |
{
"status": "success",
"data": {
"totalCount": 10,
"results": [
{
"id": "5f4d8...001",
"name": "..."
}
]
}
}
Hata Kodları (Responses)
- 404 Not Found: Çağrılan id (Ülke, Eyalet ya da Şehir ID'si) veritabanı kayıtlarında bulunamazsa hata patlatır.
- 422 Unprocessable Entity: Zorunlu argüman eksiklikleri, tipleri (örn. limit=abc geçilmesi) ya da query argümanları değer ihlalleri.
- 429 Too Many Requests: SlowAPI Limit toleransının (Genellikle 60 req/min) aşılması durumudur. Client'ın bir sonraki 1 dakika beklemesi istenir.