canonical: https://jentic.com/apis/countrystatecity.in/countrystatecity-countrystatecity

# Countrystatecity In Country State City API

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 without bundling a static dataset.

## For AI agents

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

## Scope

Does not perform IP geolocation, postal-code validation, or live geocoding - use for hierarchical country/state/city reference data only.

## Capabilities

- 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
- List every city in a given state of a given country
- Power cascading country to state to city dropdowns from one source

## Use cases

### 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.

Example prompt: 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.

Example prompt: 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 like 'NY' versus 'New York'.

Example prompt: 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.

Example prompt: 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

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

## Key resources

- **Countries** — List or look up countries by ISO2 code
- **States** — List all states or filter by country, or look up a specific state
- **Cities** — List cities scoped to a country or to a country plus state

## Why Jentic

- **Setup:** Wiring the Country State City API by hand means handling its X-CSCAPI-KEY header auth, pinning the v1 host, and coding your own walk down the country, state, and city hierarchy. Through Jentic you install once, import the Country State City API from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** This API is read-only hierarchical reference data where iso2 and state codes are lookup values in the path, not permissionable resources, so scope by operation: limit the agent to the operations it needs, such as listing states or cities for a country. You choose the operations it may call, so it stays limited to those reads.
- **Credential handling:** Your Country State City API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list states in a country' or 'get cities for a state', and Jentic returns the matching Country State City operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Countrylayer API** — Country-level reference data with currency, language, and calling code
- **country.is** — Free no-auth IP-to-country code lookup
- **ipapi** — IP geolocation that returns country, region, and city directly
- **Abstract Geolocation API** — Commercial geolocation enrichment from IP

## FAQ

### 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 your Jentic One instance 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.

### Can I limit what my agent is allowed to do with the Country State City API?

Yes. Because you run your own self-hosted Jentic One instance, your own rules decide which Country State City operations and credentials the agent can use. Since this API is read-only reference data, you scope by operation: allow only the reads the agent needs, such as GET /countries or GET `/countries/{iso2}/states`, while withholding the broader GET /states or city lookups. The X-CSCAPI-KEY is injected at execution and never enters the agent's context, so the agent stays limited to exactly the lookups you permit.