Search by task, endpoint, field, or error.

← Docs

State API

A state or province by code or name, with timezones.

Look up a state or province by code or name. /state/colorado and /state/texas resolve on their own. CA is shared across countries, so pass ?country=US for California. ISO2, ISO3, and names all work. Accents optional.

Lookup

GET
api.parseapi.com/state/{code}
State or province by code or name. ?country= when it collides
Explore
Parameters 4
codestring · path · required

State or province code or name (NC, colorado, ontario)

countrystring · query · optional

ISO2, ISO3, or a country name. Optional when the code or name is globally unique. A collision 404s asking for it.

langstring · query · optional

Display language as one BCP 47 tag, such as fr or zh-Hant. Changes supported display labels only; IDs, codes, native names, facts, parsing and deep access stay unchanged. Omit for the original response. Unsupported regions use the supported language base; unsupported languages or scripts use English. Missing labels retain their source value. Accept-Language is not read automatically. Available on the current API contract; frozen 1.0.0 is unchanged.

Length: 2 to 64 characters

deepboolean · query · optional

Population, area, capital, area codes and tax references. Included on paid plans.

Run uses the free demo on API 2.0.0. Copied code uses your API key when signed in, or YOUR_API_KEY when signed out.

SDK quickstart
import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.state("BY", { country: "DE" });
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response
{
  "state": "BY",
  "name": "Bavaria",
  "name_local": "Bayern",
  "type": "land",
  "country": "DE",
  "country_name": "Germany",
  "latitude": 48.946756,
  "longitude": 11.403872,
  "timezone": "Europe/Berlin",
  "timezones": [
    "Europe/Berlin"
  ],
  "iso_3166_2": "DE-BY"
}

Response fields

statestring
State or province code
namestring or null
Name
name_localstring or null
Local-language name, null when absent or identical to name
typestring or null
State, province, etc.
countrystring or null
ISO2 country code
country_namestring or null
Country name
latitudenumber or null
Centroid latitude
longitudenumber or null
Centroid longitude
timezonestring or null
Primary timezone (most-populated zone)
timezonesarray or null
Every IANA timezone in the state
iso_3166_2string or null
ISO 3166-2 code (US-CO)

Districts / counties in a state

Counties, parishes, boroughs, and the like under that state. Useful for finer address forms.

GET
api.parseapi.com/state/{code}/districts
Districts and counties in a state
Explore
Parameters 4
codestring · path · required

State / province code or name

countrystring · query · optional

ISO2, ISO3, or a country name. Optional when the code is globally unique.

langstring · query · optional

Display language as one BCP 47 tag, such as fr or zh-Hant. Changes supported display labels only; IDs, codes, native names, facts, parsing and deep access stay unchanged. Omit for the original response. Unsupported regions use the supported language base; unsupported languages or scripts use English. Missing labels retain their source value. Accept-Language is not read automatically. Available on the current API contract; frozen 1.0.0 is unchanged.

Length: 2 to 64 characters

deepboolean · query · optional

Population, area, capital, area codes and tax references. Included on paid plans.

Run uses the free demo on API 2.0.0. Copied code uses your API key when signed in, or YOUR_API_KEY when signed out.

SDK quickstart
import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.state.districts("nc", { country: "US" });
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response (excerpt)

This example shows selected fields or shortened lists. Run the request for the full response.

{
  "state": "NC",
  "state_name": "North Carolina",
  "country": "US",
  "country_name": "United States",
  "districts": [
    {
      "district": "37119",
      "name": "Mecklenburg",
      "type": "county"
    },
    {
      "district": "37063",
      "name": "Durham",
      "type": "county"
    }
  ]
}

Response fields

statestring
State or province code
state_namestring or null
State or province name
countrystring or null
ISO2 country code
country_namestring or null
Country name
districtsarray
Every district in the state
districts[].districtstring or null
District code
districts[].namestring or null
District name
districts[].typestring or null
County, department, etc.

Deep

?deep=true Population, area, capital, area codes and tax references. Included on paid plans.

Run this Deep example with a paid-plan key. Deep is included in the pooled request, with no separate lookup charge.

SDK quickstart
import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.state("BY", { country: "DE", deep: true });
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response
{
  "state": "BY",
  "name": "Bavaria",
  "name_local": "Bayern",
  "type": "land",
  "country": "DE",
  "country_name": "Germany",
  "latitude": 48.946756,
  "longitude": 11.403872,
  "timezone": "Europe/Berlin",
  "timezones": [
    "Europe/Berlin"
  ],
  "iso_3166_2": "DE-BY",
  "deep": {
    "population": 13435062,
    "population_period": null,
    "area": 70551,
    "capital": "Munich"
  }
}

Deep fields

deep.populationinteger or null
Population estimate
deep.population_periodstring or null
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.areanumber or null
Total area in km²
deep.fipsstring or null
US Census FIPS code. Null outside the US
deep.capitalstring or null
Capital or seat of government
deep.area_codesarray or null
Telephone area codes (NANP countries)
deep.taxstring or null
State or province levy name (Sales tax, HST, GST + PST). Null when unavailable or no levy is named
deep.tax_ratenumber or null
State or province reference rate in percent. May already include national tax; do not add the country rate

Display language

Pass lang with a language tag such as fr, pt-BR, or zh-Hant. Existing country_name and separately sourced state or district names when available.

Omitting lang preserves the original response. Codes, IDs, numeric facts and native-name fields stay unchanged. Missing translations keep their existing source value; unknown values stay null. A preserved name_local may equal the translated name.

Send a chosen browser preference explicitly, for example { lang: navigator.language } in your JavaScript SDK options. The API does not read Accept-Language automatically. Unsupported regions fall back to their supported base language; unsupported languages or scripts use English. Empty, invalid or repeated tags return 400.

Content-Language identifies languages used in translated display fields and known English fallbacks. This option follows the current API contract. Requests selecting frozen 1.0.0 retain that contract. Select API 2.0.0 to use display language.

41 display language choices
Language tagLanguage
enAmerican English
zh-Hans简体中文
frfrançais (France)
deDeutsch
ititaliano
ja日本語
ko한국어
esespañol de España
arالعربية
bgбългарски
cacatalà
hrhrvatski
csčeština
dadansk
nlNederlands
fisuomi
elΕλληνικά
heעברית
hiहिन्दी
humagyar
idIndonesia
kkқазақ тілі
msMelayu
nbnorsk bokmål
plpolski
ptportuguês (Brasil)
roromână
ruрусский
skslovenčina
svsvenska
thไทย
trTürkçe
ukукраїнська
viTiếng Việt
zh-Hant繁體中文
en-AUAustralian English
en-GBBritish English
fr-CAfrançais canadien
es-419español latinoamericano
pt-PTportuguês europeu
zh-Hant-HK繁體中文（中國香港特別行政區）

Questions? Email