Country API

Every country, in one endpoint.

A REST endpoint for every sovereign state and dependent territory, with ISO 3166-1 codes, dial codes, currencies, capitals, regions and coordinates. JSON over REST, with GraphQL on eligible paid plans. The free tier needs no card.

250 countries and territories
JSON responses
3,000 free requests / mo

Coverage varies by release. Check the API statistics and database releases for current data. Read the ODbL-1.0 licence before using the database.

Request200 OK
curl --location 'https://api.countrystatecity.in/v1/countries/IN' \
  --header 'X-CSCAPI-KEY: YOUR_API_KEY'
Community response excerpt
{
  "id": 101,
  "name": "India",
  "iso2": "IN",
  "iso3": "IND",
  "phonecode": "91",
  "capital": "New Delhi",
  "currency": "INR",
  "latitude": "20.00000000",
  "longitude": "77.00000000"
}

Endpoints

These endpoints are served from https://api.countrystatecity.in/v1 and require your key in the X-CSCAPI-KEY header. Availability depends on your plan.

GET/countriesList countries and territories
GET/countries/{ciso}One country by ISO2 code or numeric id
GET/iso/countryLook a country up by any ISO code
GET/iso/country/convertConvert between ISO2, ISO3 and numeric
GET/subregions/{id}/countriesCountries within a UN subregion

Available fields for country records.

Fields depend on your plan and may be missing or null. On eligible plans, select fields with ?fields=. Compare plan access.

idStable numeric identifier
nameEnglish name
iso2ISO 3166-1 alpha-2
iso3ISO 3166-1 alpha-3
numeric_codeISO 3166-1 numeric
phonecodeInternational dial code
capitalCapital city
currencyISO 4217 code
currency_nameCurrency in words
currency_symbolDisplay symbol
tldCountry-code top-level domain
nationalityDemonym
nativeName in the local script
regionUN region
subregionUN subregion
timezonesPublished timezone entries, when available
latitudeCentroid latitude
longitudeCentroid longitude
emojiFlag emoji
emojiUFlag emoji code points
populationWhen available; may be null
gdpWhen available; may be null
area_sq_kmLand area
postal_code_formatExpected postcode shape
postal_code_regexValidation pattern
translationsName in other languages
wikiDataIdWikidata item

What people build with it.

  • Country dropdowns in a signup or checkout form, with flags and dial codes already attached.
  • Validating a shipping address against the right postcode pattern before you call a carrier.
  • Converting between ISO2, ISO3 and numeric codes when two systems disagree.
  • Routing or pricing by UN region and subregion rather than by a hand-kept list.
Build a React location dropdown with the browser package →

Questions.

Is the country API free?

Community includes 3,000 requests per calendar month and 100 per day with basic fields, an API key and no card. Paid plans add higher limits, extra fields and endpoints. GraphQL and field selection depend on your plan; compare the current plans for availability.

How many countries does it return?

250 country and territory records. Check the countries endpoint for the current entries and codes. Coverage and downloadable snapshots can differ by release.

Can I get the data offline instead of over HTTP?

Yes. The same dataset is published as SQL, JSON, CSV, XML and more through the export tool and the open-source database, so you can ship it inside your application.

How often does the country data change?

Maintainers publish corrections to the underlying dataset and API. The /changes feed supports incremental syncing on eligible plans; check the current documentation for availability and retention.

Free up to 3,000 requests a month.

Paid plans from $5 add higher limits. Supporter adds fuzzy search; Professional adds GraphQL and the change feed.