Skip to main content
GET
/
v1
/
iso
/
country
curl -X GET 'https://api.countrystatecity.in/v1/iso/country?iso2=US' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

{
  "id": 233,
  "name": "United States",
  "iso2": "US",
  "iso3": "USA",
  "numeric_code": "840"
}

Documentation Index

Fetch the complete documentation index at: https://docs.countrystatecity.in/llms.txt

Use this file to discover all available pages before exploring further.

Look up a single country by any one of the three ISO 3166-1 codes: 2-letter (alpha-2), 3-letter (alpha-3), or 3-digit numeric. Exactly one query parameter must be provided. This is the canonical lookup when you have an ISO code from an external system (payment gateway, geolocation service, address parser) and need to resolve it to the country record.
Availability: Starter plan and above. Returns 403 on Community plan.
Responses are cached server-side for 1 hour. The cache slot is shared with /v1/iso/country/convert — warming the cache via one endpoint serves the other for free. Numeric codes 4 and 004 resolve to the same cache slot.

​
Authentication

​
X-CSCAPI-KEY
string
required
Your API key for authentication

​
Query Parameters

Provide exactly one of the three. Sending two or zero returns 400.
​
iso2
string
ISO 3166-1 alpha-2 code, e.g. US, IN, DE. Case-insensitive (auto-uppercased).
​
iso3
string
ISO 3166-1 alpha-3 code, e.g. USA, IND, DEU. Case-insensitive.
​
numeric
string
ISO 3166-1 numeric code, 1–3 digits. Accepts padded (004) and unpadded (4) forms. All-zero values are rejected.

​
Response

​
id
integer
Internal CSC country ID — same value used by /v1/countries/:id and other foreign-key references.
​
name
string
Official country name in English.
​
iso2
string
ISO 3166-1 alpha-2 code (e.g. "US").
​
iso3
string
ISO 3166-1 alpha-3 code (e.g. "USA").
​
numeric_code
string | null
ISO 3166-1 numeric code, zero-padded to 3 digits (e.g. "840"). null for entries without an assigned numeric code.
curl -X GET 'https://api.countrystatecity.in/v1/iso/country?iso2=US' \
  -H 'X-CSCAPI-KEY: YOUR_API_KEY'

{
  "id": 233,
  "name": "United States",
  "iso2": "US",
  "iso3": "USA",
  "numeric_code": "840"
}