Countrystatecity In Country State City API

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

✓ Official Vendor SpecData EnrichmentAddress ValidationapiKey7 Endpoints

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.

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

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 instance

Jentic 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

GET STARTED

Start building with Country State City API

Explore with Jentic

View OpenAPI Document

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.

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

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.

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.