Countrystatecity In Country State City API
Browse all Countrystatecity In APIsOfficial vendor OpenAPI document · agent-readyData 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.
Use for: I need to list all countries with their ISO codes, Get every state in a specific country, List all cities in a state by ISO codes, Find a country record by its ISO2 code
Not supported: Does not perform IP geolocation, postal-code validation, or live geocoding - use for hierarchical country/state/city reference data only.
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.
Install Jentic One Beta
Connect the Country State City API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Country State City API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fcountrystatecity.in%2Fcountrystatecity-countrystatecity" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fcountrystatecity.in%2Fcountrystatecity-countrystatecity" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Country State City 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
List every city in a given state of a given country
Power cascading country to state to city dropdowns from one source
Use Cases
Patterns agents use Country State City 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 like 'NY' versus 'New York'.
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 — 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.
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
GET
/countries/{iso2}/cities
Get cities by country
GET
/countries/{iso2}/states/{stateIso2}/cities
Get cities by state
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Country State City API through Jentic.
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.
GET STARTED