Introduction

CSC API provides a high-performance REST API for global geographic data — 240+ countries, 5,000+ states, 150,000+ cities, and postcodes.

Base URL

https://countrystatecityapi.cloudtechsolution.co

Authentication

Send your API key in the X-API-KEY header on every request to /v1/*.

cURL
curl --request GET "https://countrystatecityapi.cloudtechsolution.co/v1/countries" \
  -H 'X-API-KEY: YOUR_KEY'

Try it

Each endpoint below has a Try it panel. Paste your API key once here — it is reused for every request on this page.

API key for Try it

Stored in this browser tab only (sessionStorage). Requests use your quota.

No key yet? Sign up or create a key.

Rate limits

Every response includes:

  • X-RateLimit-Limit — your tier's daily quota
  • X-RateLimit-Remaining — calls left today
  • X-RateLimit-Reset — when the counter resets (UTC midnight)

Countries

GET/v1/countries

List all countries with ISO codes, currency, and dial code.

GET/v1/countries/:iso2

Get a single country by ISO-2 code.

States

GET/v1/countries/:iso2/states

List states for a country.

GET/v1/countries/:iso2/states/:stateCode

Get a state by ISO sub-division code.

Cities

GET/v1/countries/:iso2/cities

List cities for a country.

GET/v1/countries/:iso2/states/:stateCode/cities

List cities in a state.

Postcodes

GET/v1/countries/:iso2/postcodes

List postcodes for a country. Optional query: state_code, q, limit, offset.

GET/v1/countries/:iso2/postcodes/:code

Lookup postcode(s) by code within a country (always scope by country — codes repeat globally).

GET/v1/countries/:iso2/states/:stateCode/postcodes

List postcodes in a state.

Errors

CodeDescription
200Success.
401API key missing or invalid.
403API key revoked or subscription inactive.
404Resource not found.
429Rate limit exceeded for the day. Check X-RateLimit-Reset.

Data attribution

Countries, states, cities, and postcodes are sourced from the open dr5hn/countries-states-cities-database project (ODbL). India PIN rows use the india-post pipeline documented upstream. The Free tier requires attribution; paid tiers do not.

Ready to integrate?

Create an account and grab your first API key.

Get an API key