Country State City API

Name: Country State City API API
Brand: Country State City API
Availability: InStock

★ Only Publicly Available OpenAPI DocumentData EnrichmentAddress ValidationapiKey7 EndpointsREST

For Agents

Look up countries, states or provinces, and cities in a structured hierarchy. Suitable for cascading address dropdowns, territory mapping, and region-aware filtering.

Quickstart

Get started with Country State City API in minutes using your preferred integration method.

# Add to your MCP client config (Claude Desktop, Cursor, Windsurf)
{
  "jentic": {
    "url": "https://api.jentic.com/mcp",
    "auth": "oauth"
  }
}

# Then ask your agent:
"list states in a country"

# → Jentic returns the GET /events tool with parameter schema, agent executes.

Capabilities

What an agent can do with Country State City API API.

Retrieve every country in the dataset with ISO2 and ISO3 codes

Resolve a single country by ISO2 code

List every state or province in a given country

Resolve a specific state by country ISO2 plus state ISO2

List every city in a given country

GET STARTED

Start building with Country State City API API

Explore with Jentic

View OpenAPI Document

Jentic publishes the only available OpenAPI document for Country State City API, keeping it validated and agent-ready.

Jentic publishes the only available OpenAPI specification for Country State City API, keeping it validated and agent-ready. The Country State City API is a global geographical reference dataset exposed as a REST API, covering 247+ countries, 5000+ states or provinces, and 151,000+ cities across 7 endpoints. Authentication is via the X-CSCAPI-KEY header on the v1 base URL, with sub-100 ms response times reported globally. It suits address forms, region-aware analytics, shipping zones, sales territory mapping, and any workflow that needs hierarchical country to state to city drill-down.

Use Cases

Patterns agents use Country State City API API for, with concrete tasks.

★ Cascading Address Dropdowns

Power signup, checkout, and shipping forms with country, state, and city dropdowns that depend on each other. Calling GET /countries fills the first dropdown, GET /countries/{iso2}/states fills the second once a country is picked, and GET /countries/{iso2}/states/{stateIso2}/cities fills the third. Sub-100 ms global latency keeps the UI responsive.

On country selection, call GET /countries/IN/states to populate the state dropdown, then on state selection call GET /countries/IN/states/MH/cities to populate the city dropdown

Sales Territory Mapping

Build sales territory and quota dashboards that roll up to country, state, or city granularity. Pull the canonical hierarchy once via GET /countries plus GET /states, cache it, and join against CRM records by ISO codes. Avoids the drift that comes with maintaining a region table by hand.

Pull GET /countries and GET /states once, store both in a warehouse table, and join the CRM `account.country_iso2` column against it

Region-Aware Analytics

Slice product or marketing analytics by city, state, or country using a stable ISO-code hierarchy. The API gives every city a consistent identifier that you can attach to events at write time, then aggregate up to state or country level later without ambiguous string matches.

Resolve every event's free-text city to a city record via GET /countries/{iso2}/cities and store the API's numeric city id alongside the event

AI Agent Address Resolution

Let an AI agent resolve unstructured address fragments — 'Mumbai, India' or 'Bavaria' — into canonical country, state, or city records. Through Jentic, the agent searches by intent and the X-CSCAPI-KEY stays in the encrypted vault, so even a chat-based agent never sees the raw key.

Use Jentic to search 'list states in a country', load the schema for GET /countries/{iso2}/states, and execute it with the country ISO2 code derived from the user input

Key Endpoints

7 endpoints — jentic publishes the only available openapi specification for country state city api, keeping it validated and agent-ready.

METHOD

PATH

DESCRIPTION

GET

/countries

Get all countries

GET

/countries/{iso2}

Get a country by ISO2 code

GET

/states

Get all states across every country

GET

/countries/{iso2}/states

Get states by country

GET

/countries/{iso2}/states/{stateIso2}

Get a state by ISO codes

GET

/countries/{iso2}/cities

Get cities by country

GET

/countries/{iso2}/states/{stateIso2}/cities

Get cities by state

GET

/countries

Get all countries

GET

/countries/{iso2}

Get a country by ISO2 code

GET

/states

Get all states across every country

GET

/countries/{iso2}/states

Get states by country

GET

/countries/{iso2}/states/{stateIso2}

Get a state by ISO codes

Why though Jentic?

Three things that make agents converge on Jentic-routed access.

Credential isolation

X-CSCAPI-KEY values are stored encrypted in the Jentic MAXsystem vault. Agents call the API through Jentic with a scoped session token, so the raw key never enters prompts or logs.

Intent-based discovery

Agents search Jentic with intents like 'list cities in a country' and Jentic returns the matching Country State City operation with its parameter schema, so the agent calls the right endpoint without reading the spec.

Time to first call

Direct integration: 2-3 hours to wire the X-CSCAPI-KEY header, handle cascading lookups, and cache the dataset. Through Jentic: under 30 minutes to search, load, and execute.

Related APIs

Alternatives and complements available in the Jentic catalogue.

Alternative

Countrylayer API

Country-level reference data with currency, language, and calling code

Choose Countrylayer when only country metadata is needed and state or city granularity is not

Complementary

country.is

Free no-auth IP-to-country code lookup

Use country.is to resolve a visitor's IP to an ISO2 code, then call Country State City to drill into states and cities

Complementary

ipapi

IP geolocation that returns country, region, and city directly

Use ipapi when the input is an IP address rather than a country code

Alternative

Abstract Geolocation API

Commercial geolocation enrichment from IP

Choose Abstract Geolocation for IP-to-region enrichment rather than canonical reference data

FAQs

Specific to using Country State City API API through Jentic.

Why is there no official OpenAPI spec for Country State City API?

countrystatecity.in does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Country State City API via structured tooling. It is validated against the live API and kept up to date. Get started at https://app.jentic.com/sign-up.

What authentication does the Country State City API use?

The Country State City API authenticates via an API key passed in the `X-CSCAPI-KEY` request header. When called via Jentic, the key is stored encrypted in the MAXsystem vault and the agent receives a scoped session token rather than the raw key.

Can I retrieve every city in a country with one call?

Yes. GET /countries/{iso2}/cities returns every city the dataset has for the given country. For example, /countries/IN/cities returns India's cities. For a state-scoped subset, use GET /countries/{iso2}/states/{stateIso2}/cities.

How big is the underlying dataset?

The dataset covers 247+ countries, 5000+ states or provinces, and 151,000+ cities globally, all reachable through the same v1 base URL. Records share consistent ISO2 keys so you can join them across endpoints.

What are the rate limits for the Country State City API?

Rate limits are governed by the API key's plan tier. The free tier is suitable for development and low-volume read traffic; higher-volume use cases should select a paid plan from countrystatecity.in. Cache responses aggressively because the underlying dataset changes infrequently.

How do I drill from country to state to city through Jentic?

Search Jentic for 'list states in a country', execute GET /countries/{iso2}/states, then chain into GET /countries/{iso2}/states/{stateIso2}/cities using the resulting state ISO2 code. Jentic handles the X-CSCAPI-KEY header from the vault.

Does the API include latitude and longitude for cities?

Yes. City records returned by /countries/{iso2}/cities and /countries/{iso2}/states/{stateIso2}/cities include latitude and longitude fields, which can be used for distance calculations or rough mapping without calling a separate geocoder.