A code or name for the state record. /districts for every district or county in it.

Not when the code or name is unique. colorado and texas resolve on their own. CA matches 12 states, so pass ?country=US. Country takes ISO2, ISO3, or a name.

Name, type, country, coordinates, timezones, and subdivision code. Paid deep adds population, area, capital, area codes, FIPS, and tax references.

The kind of division. State, province, prefecture, oblast.

How do I list districts?

GET /state/{code}/districts returns district names, codes, and types. Add deep=true on a paid plan for population inside each district detail bag.

GET /state/{code} · /{code}/districts

State API

Pass colorado, texas, or ontario. The state, country, and timezones.

You have a code or a name. Capital, tax, area codes.

Example response/state/colorado

{
  "state": "CO",
  "name": "Colorado",
  "name_local": null,
  "type": "state",
  "country": "US",
  "country_name": "United States",
  "latitude": 38.725178,
  "longitude": -105.607716,
  "timezone": "America/Denver",
  
    "America/Denver"
  ],
  "iso_3166_2": "US-CO",
  ?deep=true
}

1M requests · $20/mo. Get started

What comes back.

name

Name

type

State, province, etc.

deep.capital

Capital or seat of government

timezones

Every IANA timezone in the state

deep.area_codes

Telephone area codes (NANP countries)

deep.tax

State or province levy name (Sales tax, HST, GST + PST). Null when unavailable or no levy is named

deep.tax_rate

State or province reference rate in percent. May already include national tax; do not add the country rate

deep.fips

US Census FIPS code. Null outside the US

districts

Every district in the state

Pass a code or the name

/state/colorado and /state/texas resolve on their own. CA needs ?country=US.

Get the facts

Name, type, country, coordinates, and timezones. Paid deep adds the capital, statistics, area codes, and tax references.

List districts

Districts hang off the state path.

Coverage

Official admin divisions in 229 countries.

NANorth America38 countries
EUEurope50 countries
AFAfrica57 countries
ASAsia48 countries
OCOceania22 countries
SASouth America13 countries
ANAntarctica1 countries

229
countries covered: 5,308
states and provinces: 3,680
districts listed

Look up a state or province by code or name. colorado and texas resolve on their own. A shared code needs country; CA with country=US selects California.

Name, type, country, coordinates, and timezones form the ordinary response. Paid deep adds the capital, population, area, area codes, US FIPS, and tax references. /state/{code}/districts lists district names and codes; paid deep adds population to each district.

SPEED

How long /state takes.

Median time to first byte over the last seven days. Warm requests, measured every 30 minutes. Live verification and other request variants can take longer.

20ms

22ms

APAC

36ms

LatAm

30ms

95ms

See live status →

Make your first request.

One key works across the APIs. Copy a request in your language and get JSON back.

curl "https://api.parseapi.com/state/colorado" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Parse-Version: 2.0.0"

// Example response · 200
{
  "state": "CO",
  "name": "Colorado",
  "name_local": null,
  "type": "state",
  "country": "US",
  "country_name": "United States",
  "latitude": 38.725178,
  "longitude": -105.607716,
  "timezone": "America/Denver",
  "timezones": ["America/Denver"],
  "iso_3166_2": "US-CO"
}

API reference SDKs Keys and authentication

Every response field

Response fields

state: State or province code
name: Name
name_local: Local-language name, null when absent or identical to name
type: State, province, etc.
country: ISO2 country code
country_name: Country name
latitude: Centroid latitude
longitude: Centroid longitude
timezone: Primary timezone (most-populated zone)
timezones: Every IANA timezone in the state
iso_3166_2: ISO 3166-2 code (US-CO)

Deep fields

deep.population: Population estimate
deep.population_period: Observation year or multi-year period for this population estimate (YYYY or YYYY-YYYY). Null when the record has no verified period or population. Never the import date.
deep.area: Total area in km²
deep.fips: US Census FIPS code. Null outside the US
deep.capital: Capital or seat of government
deep.area_codes: Telephone area codes (NANP countries)
deep.tax: State or province levy name (Sales tax, HST, GST + PST). Null when unavailable or no levy is named
deep.tax_rate: State or province reference rate in percent. May already include national tax; do not add the country rate

QUESTIONS

When do I use which?: A code or name for the state record. /districts for every district or county in it.
Do I need a country?: Not when the code or name is unique. colorado and texas resolve on their own. CA matches 12 states, so pass ?country=US. Country takes ISO2, ISO3, or a name.
What comes back?: Name, type, country, coordinates, timezones, and subdivision code. Paid deep adds population, area, capital, area codes, FIPS, and tax references.
What is type?: The kind of division. State, province, prefecture, oblast.
How do I list every state in a country?: GET /country/{code}/states.
How do I list districts?: GET /state/{code}/districts returns district names, codes, and types. Add deep=true on a paid plan for population inside each district detail bag.

All 50 two-letter codes plus DC and territories in the abbreviations list.

Get the state straight.

State codes and names on every plan. Detailed profiles on paid plans.

Start includes 1M API requests a month for $20/mo.

Get started Compare plans Read the docs