API'ler

Türkiye Adres API

OAS3 v1.0.0 application/json

Genel Bakış

Türkiye Adres API, Türkiye'nin yönetimsel coğrafi yapılanmasını (İl, İlçe, Mahalle) sağlayan açık (public), asenkron ve okumaya dayalı (Read-Only) bir RESTful servistir. İstemcilere performansı maksimize edilmiş JSON yanıtları döner ve coğrafi hiyerarşiyi koruyarak adres yapılandırmasını kurmalarını sağlar.

Yapılandırma & Kurallar

Endpoints

GET /api/v1/iller/{id} İller (Provinces) Endpoint'i

ID bazlı olarak tek bir ilin kaydını getirir.

Parameters
Name Description
parameter string Tüm İlleri Listeleme:
parameter string Spesifik İl Detayı:
Responses 200 OK 
{
    "status": "success",
    "data": {
        "totalCount": 10,
        "results": [
            {
                "id": "5f4d8...001",
                "name": "..."
            }
        ]
    }
}
GET /api/v1/ilceler/{id} İlçeler (Districts) Endpoint'i

İlgili id'ye sahip ilçeyi ve foreign_key üzerinden üst bileşeni olan bağlı olduğu ili döner.

Parameters
Name Description
parameter string İl'e Göre Filtreleyerek Listeleme:
il_id path / Zorunlu Query Parametresi Listelenecek ilçelerin bağlı olduğu il id'si.
parameter string Spesifik İlçe Detayı:
Example Request
curl -X 'GET' \
'https://api.sonercreative.com/api/v1/ilceler?il_id=34' \
-H 'accept: application/json'
Responses 200 OK 
{
    "status": "success",
    "data": {
        "totalCount": 10,
        "results": [
            {
                "id": "5f4d8...001",
                "name": "..."
            }
        ]
    }
}
GET /api/v1/mahalleler/{id} Mahalleler (Neighborhoods) Endpoint'i

Spesifik mahalle bilgisini; bağlı olduğu ilçe ve il bilgileriyle (JOIN query) beraber döner.

Parameters
Name Description
parameter string İlçe'ye veya İl'e Göre Listeleme:
parameter string {il_id} (Opsiyonel)
parameter string {ilce_id} (İlçe bazlı performans için tercih edilir - Opsiyonel)
parameter string Spesifik Mahalle Detayı:
Example Request
curl -X 'GET' \
'https://api.sonercreative.com/api/v1/mahalleler?ilce_id=1234' \
-H 'accept: application/json'
Responses 200 OK 
{
    "status": "success",
    "data": {
        "totalCount": 10,
        "results": [
            {
                "id": "5f4d8...001",
                "name": "..."
            }
        ]
    }
}
GET /api/v1/search/ Arama (Search)

İl, ilçe ve mahalle tabloları üzerinde asenkron tam metin (like) araması yapar ve eşleşen tüm lokasyonları { "iller": [], "ilceler": [], "mahalleler": [] } JSON yapısında sınıflandırarak döner.

Parameters
Name Description
Çoklu Tablo Akıllı Arama query / Fuzzy Search
parameter string {q} (Zorunlu Query Parametresi
parameter string minimum 2 karakter uzunluk)
Example Request
curl -X 'GET' \
'https://api.sonercreative.com/api/v1/search/?q=Beşik' \
-H 'accept: application/json'
Responses 200 OK 
{
    "status": "success",
    "data": {
        "totalCount": 10,
        "results": [
            {
                "id": "5f4d8...001",
                "name": "..."
            }
        ]
    }
}

Hata Kodları (Responses)