Search Address

This service queries the existence of a keyword within a given country by Country ISO2 code and search keyword across breakdowns such as Postal Code, State, City, and Place. If a match is successful, it returns the address information with various details as a response.

Endpoint Information

Property Value
URL {{APP_URL}}/api/v1/address/search
HTTP Method GET
Content Type application/json
Authentication APIKEY header

Request Parameters

URL Query Parameters

Parameter Name Parameter Type Required Description
countryIso2 String (ISO2) Required Search Country Code (Must be in ISO2 format)
keyword String Required Search Keyword (Must not be empty)
searchFields[] Array Required Fields to search (At least 1 field must be defined). This field can only contain these types: postalCode, city, state, place. Must be sent as query params array type.
page Integer Optional Requested page number. Use this parameter to navigate to other pages if records span multiple pages. Default is set to 1.
limit Integer Optional Maximum number of records per page. This limit is set to 10 by default. Can be set to a maximum of 100.

Example Usage

API Request

Below is an example HTTP raw request for the API request.

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 Response

On a successful request, the API will return a response like the following:

{
    "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
    }
}

Error Responses

If the API request fails, the API will return an error response like the following:

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

Example Search 1

In this search, a search for Kzkalesi data was performed in the city, state, and place fields within the country with TR ISO2 code.

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}}

Example Search 1 Response Result: As seen in the result; search results are presented under the results parameter, while pagination meta information is provided in other parameters. Even though the search was performed incorrectly as Kzkalesi, the search system found and returned the closest matches using the necessary fuzzy and ngram algorithms.

{
    "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
    }
}

Example Search 2

In this search, a search for 34104 data was performed in the postalCode field within the country with TR ISO2 code.

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

Example Search 2 Response Result: The response for this postal code search is as follows.

{
    "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
    }
}