Adres Ara

Bu servis, Ülke ISO2 kodu ve arama keywordu verilerek bu keywordun ilgili ülke içerisinde Posta Kodu, İl, İlçe, Kasaba gibi kırılımlarda varlığını sorgular. Eğer eşleşme başarılı olur ise, adres bilgisini çeşitli bilgiler ile yanıt olarak verir.

Endpoint Bilgileri

URL: {{APP_URL}}/api/v1/address/search
HTTP Metodu: GET
İçerik Türü: application/json
Kimlik Doğrulama Tipi: APIKEY

İstek Parametreleri

URL Query Parametreleri

Parametre Adı	Parametre Tipi	Zorunluluk	Açıklama
`countryIso2`	String (ISO2)	Zorunlu	Arama Ülke Kodu (ISO2 Formatında olmalı)
`keyword`	String	Zorunlu	Arama Kelimesi (Boş olmamalı)
`searchFields[]`	Array	Zorunlu	Aranacak Alanlar (En az 1 alan tanımlanmalı). Bu alan sadece şu tipleri içerebilir: `postalCode`, `city`, `state`, `place`. Query params array tipinde gönderilmelidir.
`page`	Integer	İsteğe Bağlı	İstenen sayfa numarası. Eğer kayıtlar birden fazla sayfadan oluşuyor ise diğer sayfalara geçmek için bu parametreyi kullanınız. Varsayılan 1 olarak tanımlanmıştır.
`limit`	Integer	İsteğe Bağlı	Bir sayfada olabilecek maksimum kayıt sayısıdır. Bu limit varsayılan 10 olarak tanımlanmıştır. Maksimum 100 olarak tanımlanabilir.

Örnek Kullanım

API İsteği

Aşağıda, API isteği için bir örnek HTTP raw request bulunmaktadır.

GET {{APP_URL}}/api/v1/address/search?searchFields[]=city&searchFields[]=state&searchFields[]=place&countryIso2=TR&keyword=Kzkalesi&page=1&limit=10
Content-Type: application/json
APIKEY: {{APIKEY}}

API Cevabı

Başarılı bir istekte, API aşağıdaki gibi bir yanıt döndürecektir:

{
    "status": true,
    "message": null,
    "data": {
        "results": [
            {
                "stateCode": "31",
                "countryIso2": "TR",
                "city": "Altinözü",
                "state": "Hatay",
                "postalCode": "31750",
                "place": "Kozkalesi"
            },
            {
                "stateCode": "32",
                "countryIso2": "TR",
                "city": "Erdemli",
                "state": "Mersin(İçel)",
                "postalCode": "33790",
                "place": "Kizkalesi"
            }
        ],
        "page": 1,
        "lastPage": 1,
        "limit": 10,
        "total": 2
    }
}

Hata Cevapları

API isteği başarısız olursa, API aşağıdaki gibi bir hata yanıtı döndürecektir:

{
    "status": false,
    "errors": [
        {
            "message": "Invalid countryIso2 code"
        }
    ]
}

Örnek Arama 1

Bu aramada TR iso2 kodlu ülke içerisinde, city, state ve place alanlarında Kzkalesi verisi araması yapılmıştır.

GET {{APP_URL}}/api/v1/address/search?searchFields[]=city&searchFields[]=state&searchFields[]=place&countryIso2=TR&keyword=Kzkalesi&page=1&limit=10
Content-Type: application/json
APIKEY: {{APIKEY}}

Örnek Arama 1 Yanıt Sonucu: Sonuçta görüldüğü gibi; results parametresi altında arama sonuçları, diğer parametrelerde ise sayfalama ile ilgili meta bilgiler sunulmuştur. Yapılan arama Kzkalesi şeklinde yanlış olsa bile arama sistemi gerekly fuzzy ve ngram algoritmaları ile en yakın eşleşmeleri bulup getirmiştir.

{
    "status": true,
    "message": null,
    "data": {
        "results": [
            {
                 "stateCode": "31",
                "countryIso2": "TR",
                "city": "Altinözü",
                "state": "Hatay",
                "postalCode": "31750",
                "place": "Kozkalesi"
            },
            {
                "stateCode": "33",
                "countryIso2": "TR",
                "city": "Erdemli",
                "state": "Mersin(İçel)",
                "postalCode": "33790",
                "place": "Kizkalesi"
            }
        ],
        "page": 1,
        "lastPage": 1,
        "limit": 10,
        "total": 2
    }
}

Örnek Arama 2

Bu aramada TR iso2 kodlu ülke içerisinde, postalCode alanında 34104 verisi araması yapılmıştır.

GET {{APP_URL}}/api/v1/address/search?searchFields[]=postalCode&limit=100&countryIso2=TR&keyword=34104
Content-Type: application/json
APIKEY: {{APIKEY}}

Örnek Arama 2 Yanıt Sonucu: Bu yapılan posta kodu aramasına göre yanıt aşağıdaki gibidir.

{
    "status": true,
    "message": null,
    "data": {
        "results": [
            {
                "stateCode": "34",
                "countryIso2": "TR",
                "city": "Fatih",
                "state": "İstanbul",
                "postalCode": "34104",
                "place": "Şehremini"
            }
        ],
        "page": 1,
        "lastPage": 1,
        "limit": 10,
        "total": 1
    }
}