Swagger

Introduction Last updated: 2024-02-17

Welcome to the Country State City API, your go-to resource for accessing comprehensive data on countries, states, and cities worldwide.

Welcome

Welcome to the Country State City API, your go-to resource for accessing comprehensive data on countries, states, and cities worldwide. Our API, built on Laravel and powered by the open-source database provided by Crezvatic Pvt Ltd, offers developers a hassle-free solution for integrating location-based functionalities into their applications.

About Our API

Our API provides developers with easy access to accurate information about countries, states, and cities. With just a few API calls, you can retrieve a wealth of geographical data, including:

Auth   Regions   Subregions  Countries  States  Cities 

APIs

Every data endpoint requires a permanent API key. Send it as a Bearer token on every request:

Authorization: Bearer <your_api_key>

The key is shown once at registration (or regeneration) — store it then; the server can't show it again. Lose it? Call /api/auth/regenerate-token with your current key, or have an admin regenerate it from /admin. Data endpoints are not rate-limited. Login endpoints are throttled to 5 req/min per email+IP (anti-bruteforce).

Two extra features available on every list endpoint:

  • Row filtering — ?col=value on any whitelisted column. Multiple filters combine with AND. Unknown columns are silently ignored.
  • Field selection — ?fields=id,name restricts the returned columns. Unknown column names in the list are dropped; if every requested name is bogus, the full row is returned.

Auth

Register a user, sign in, view yourself, or rotate your key. Auth-protected endpoints below require Authorization: Bearer <api_key>.

Register:

Create a new user. Returns the plaintext api_key once — save it.

Method: POST

Path: /api/auth/register

Body (JSON): email_id, password (min 12 chars, mixed case, at least one number)

Response (201):
{
    "status": true,
    "message": "User registered successfully. Save this api_key — it will not be shown again.",
    "data": {
        "id": 2,
        "email_id": "you@example.com",
        "status": "inactive",
        "is_admin": false,
        "created_at": "2026-05-15T11:37:00.000000Z",
        "updated_at": "2026-05-15T11:37:00.000000Z"
    },
    "api_key": "aB3xY7p_64_chars_total_save_this_now"
}

Note: new users start with status=inactive. An admin must flip status to active before the user can call data endpoints.


Login:

Verify credentials. Does not return the api_key (use regenerate-token if lost). Throttled 5/min per email+IP.

Method: POST

Path: /api/auth/login

Body (JSON): email_id, password

Response (200):
{
    "status": true,
    "message": "Logged in successfully. If you have lost your api_key, call /api/auth/regenerate-token …",
    "data": {
        "id": 1,
        "email_id": "you@example.com",
        "status": "active",
        "is_admin": false
    }
}

Me:

Return the currently authenticated user.

Method: GET

Authorization: Bearer <api_key>

Path: /api/auth/me

Response (200):
{
    "status": true,
    "data": {
        "id": 1,
        "email_id": "you@example.com",
        "status": "active",
        "is_admin": false
    }
}

Regenerate token:

Issue a new api_key. The previous one stops working immediately. New plaintext returned once.

Method: POST

Authorization: Bearer <current_api_key>

Path: /api/auth/regenerate-token

Response (200):
{
    "status": true,
    "message": "API key regenerated. Save this api_key — it will not be shown again. The previous key has stopped working.",
    "api_key": "new_64_char_plaintext_key_save_now"
}

Regions

The 6 top-level world regions (Africa, Americas, Asia, Europe, Oceania, Polar).

Get all regions:

Method: GET

Authorization: Bearer <api_key>

Path: /api/regions

Example: /api/regions

Filterable columns:

id, name, wikiDataId

Selectable columns (?fields=):

id, name, translations, flag, wikiDataId, created_at, updated_at

Examples:
Response:
{
    "status": 200,
    "regions": [
        {
            "id": 1,
            "name": "Africa",
            "translations": "{\"kr\":\"아프리카\", \"de\":\"Afrika\", …}",
            "flag": 1,
            "wikiDataId": "Q15",
            "created_at": "2018-07-21T09:11:03.000000Z",
            "updated_at": "2023-08-08T23:04:58.000000Z"
        },
        { "…": "…" }
    ]
}

Subregions

22 subregions grouped under the 6 regions (e.g. "Western Europe", "Southern Asia").

Get all subregions:

Method: GET

Authorization: Bearer <api_key>

Path: /api/subregions

Example: /api/subregions

Filterable columns:

id, name, region_id (alias regionId kept for backwards-compat), wikiDataId

Selectable columns (?fields=):

id, name, region_id, translations, flag, wikiDataId, created_at, updated_at

Examples:
Response:
{
    "status": 200,
    "subregions": [
        {
            "id": 14,
            "name": "Southern Asia",
            "translations": "{\"de\":\"Südasien\", \"fr\":\"Asie du Sud\", …}",
            "region_id": 3,
            "flag": 1,
            "wikiDataId": "Q771405"
        },
        { "…": "…" }
    ]
}

Countries

250 countries with names, ISO codes, currency, capital, region/subregion, coordinates, translations, etc.

Get all countries:

Method: GET

Authorization: Bearer <api_key>

Path: /api/countries

Example: /api/countries

Filterable columns:

id, name, iso2, iso3, numeric_code, phonecode, capital, currency, currency_name, currency_symbol, tld, nationality, region, region_id, subregion, subregion_id

Selectable columns (?fields=):

id, name, iso3, iso2, numeric_code, phonecode, capital, currency, currency_name, currency_symbol, tld, native, region, region_id, subregion, subregion_id, nationality, timezones, translations, latitude, longitude, emoji, emojiU, wikiDataId, flag, created_at, updated_at

Examples:
Response:
{
    "status": 200,
    "countries": [
        {
            "id": 101,
            "name": "India",
            "iso3": "IND",
            "iso2": "IN",
            "numeric_code": "356",
            "phonecode": "91",
            "capital": "New Delhi",
            "currency": "INR",
            "currency_name": "Indian rupee",
            "currency_symbol": "₹",
            "tld": ".in",
            "native": "भारत",
            "region": "Asia",
            "region_id": 3,
            "subregion": "Southern Asia",
            "subregion_id": 14,
            "nationality": "Indian",
            "timezones": "[{\"zoneName\":\"Asia/Kolkata\",\"gmtOffset\":19800,…}]",
            "translations": "{\"de\":\"Indien\",\"fr\":\"Inde\",…}",
            "latitude": "20.00000000",
            "longitude": "77.00000000",
            "emoji": "🇮🇳",
            "emojiU": "U+1F1EE U+1F1F3",
            "flag": 1,
            "wikiDataId": "Q668"
        },
        { "…": "…" }
    ]
}

Get a country by id (single-object shape):

Using just ?id=X on this endpoint returns a single country wrapped in a country key instead of an array — kept for backwards compatibility. ?fields= works here too.

Method: GET

Authorization: Bearer <api_key>

Example: /api/countries?id=101

Example with fields: /api/countries?id=101&fields=id,name,iso2,currency

Response:
{
    "status": 200,
    "country": {
        "id": 101,
        "name": "India",
        "iso2": "IN",
        "currency": "INR"
    }
}

States

5,084 states / provinces / regions — scoped to a country. Three ways to scope: nested under a country (preferred, RESTful), legacy flat form, or by country name.

Nested (preferred):

Method: GET

Authorization: Bearer <api_key>

Path: /api/countries/{country_id}/states

Example: /api/countries/101/states — India

Returns 404 Country not found if country_id doesn't exist.


Legacy flat form:

Method: GET

Authorization: Bearer <api_key>

Path: /api/states/{countryId}

Example: /api/states/101 — India

Filterable columns (apply to both nested and flat forms, in addition to the path's country_id):

id, name, iso2, country_code, fips_code, type

Selectable columns (?fields=):

id, name, country_id, country_code, fips_code, iso2, type, latitude, longitude, flag, wikiDataId, created_at, updated_at

Examples:
Response:
{
    "status": 200,
    "states": [
        {
            "id": 4030,
            "name": "Gujarat",
            "country_id": 101,
            "country_code": "IN",
            "fips_code": "09",
            "iso2": "GJ",
            "type": "state",
            "latitude": "22.30850880",
            "longitude": "70.80277200",
            "flag": 1,
            "wikiDataId": "Q1061"
        },
        { "…": "…" }
    ]
}

By country name:

Same result, but the country is identified by name rather than id. Useful when you only have the human-readable name. Same filters / fields apply.

Method: GET

Authorization: Bearer <api_key>

Path: /api/states-by-name/{countryName}

Examples:

Cities

150,573 cities worldwide — scoped to a state. Three ways to scope: nested under a country and state (preferred, RESTful), legacy flat form, or by state name.

Nested (preferred):

Method: GET

Authorization: Bearer <api_key>

Path: /api/countries/{country_id}/states/{state_id}/cities

Example: /api/countries/101/states/4030/cities — Gujarat → cities

Returns 404 if the state doesn't exist or doesn't belong to the country.


Legacy flat form:

Method: GET

Authorization: Bearer <api_key>

Path: /api/cities/{stateId}

Example: /api/cities/4030 — cities in Gujarat

Filterable columns (apply to both nested and flat forms, in addition to the path's state_id):

id, name, state_code, country_id, country_code

Selectable columns (?fields=):

id, name, state_id, state_code, country_id, country_code, latitude, longitude, flag, wikiDataId, created_at, updated_at

Examples:
Response:
{
    "status": 200,
    "cities": [
        {
            "id": 134096,
            "name": "Surat",
            "state_id": 4030,
            "state_code": "GJ",
            "country_id": 101,
            "country_code": "IN",
            "latitude": "21.19594000",
            "longitude": "72.83023000",
            "flag": 1,
            "wikiDataId": "Q42941"
        },
        { "…": "…" }
    ]
}

By state name:

Same result, but the state is identified by name. Same filters / fields apply.

Method: GET

Authorization: Bearer <api_key>

Path: /api/cities-by-name/{stateName}

Examples:

Key Features

Our API, built on Laravel, offers fast, reliable performance with comprehensive, regularly updated geographical data, ensuring easy integration for developers.

Efficiency

Our API, built on Laravel, guarantees rapid response times and dependable performance, ensuring a seamless experience for your applications.

Comprehensive Data

Access an extensive database containing detailed information on countries, states, and cities across the globe, catering to diverse geographical needs.

Easy Integration

Seamlessly integrate our API into your applications with ease, thanks to our meticulously documented endpoints and user-friendly data structure.

Regular Updates

Stay up-to-date with the latest geographical information as our database undergoes frequent updates, ensuring that you always have access to accurate and current data.

Start Building Today

Unlock the power of geographical data with the Country State City API. Dive into our documentation and start building innovative applications that leverage the richness of location-based information.