← Back to Documentations

Locations API

Countries, cities and districts lookup endpoints.

Geography
V1

V1

/api/v1

First stable version.

GET /api/v1/locations/countries Auth Required
List Countries

Returns all countries ordered by name.

Authentication
X-Api-Key: your_api_key
Response Example
{
    "success": true,
    "message": "Countries fetched successfully.",
    "data": {
        "count": 2,
        "countries": [
            {
                "id": "abc123",
                "name": "Turkey",
                "slug": "turkey",
                "latitude": 38.9637,
                "longitude": 35.2433
            },
            {
                "id": "def456",
                "name": "United States",
                "slug": "united-states",
                "latitude": 37.0902,
                "longitude": -95.7129
            }
        ]
    }
}
Error Response
{
    "success": false,
    "message": "Invalid API key.",
    "error_code": "INVALID_API_KEY"
}
GET /api/v1/locations/countries/{slug} Auth Required
Get Country with Cities

Returns a single country along with its cities. Example: /locations/countries/turkey

Authentication
X-Api-Key: your_api_key
Path Parameters
Name Type Required Example Description
slug string required turkey Country slug.
Response Example
{
    "success": true,
    "message": "Country fetched successfully.",
    "data": {
        "id": "abc123",
        "name": "Turkey",
        "slug": "turkey",
        "latitude": 38.9637,
        "longitude": 35.2433,
        "city_count": 2,
        "cities": [
            {
                "id": "cty001",
                "name": "Istanbul",
                "slug": "istanbul",
                "latitude": 41.0082,
                "longitude": 28.9784
            },
            {
                "id": "cty002",
                "name": "Ankara",
                "slug": "ankara",
                "latitude": 39.9334,
                "longitude": 32.8597
            }
        ]
    }
}
Error Response
{
    "success": false,
    "message": "Country not found.",
    "error_code": "COUNTRY_NOT_FOUND"
}
GET /api/v1/locations/cities/{slug} Auth Required
Get City with Districts

Returns a single city with its country info and districts. Example: /locations/cities/istanbul

Authentication
X-Api-Key: your_api_key
Path Parameters
Name Type Required Example Description
slug string required istanbul City slug.
Response Example
{
    "success": true,
    "message": "City fetched successfully.",
    "data": {
        "id": "cty001",
        "name": "Istanbul",
        "slug": "istanbul",
        "latitude": 41.0082,
        "longitude": 28.9784,
        "country": {
            "id": "abc123",
            "name": "Turkey",
            "slug": "turkey"
        },
        "district_count": 2,
        "districts": [
            {
                "id": "dst001",
                "name": "Kadikoy",
                "slug": "kadikoy",
                "latitude": 40.9908,
                "longitude": 29.03
            },
            {
                "id": "dst002",
                "name": "Besiktas",
                "slug": "besiktas",
                "latitude": 41.0422,
                "longitude": 29.0067
            }
        ]
    }
}
Error Response
{
    "success": false,
    "message": "City not found.",
    "error_code": "CITY_NOT_FOUND"
}