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.

LookupCopy link

GET /state/{code}API Explorer ↗

State or province by code or name. ?country= when it collides

Parameters

codestring · path · required

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

formatstring · query · optional

json by default. geojson returns simplified administrative Polygon/MultiPolygon outlines with country-qualified IDs and selected facts in properties. Coordinates are longitude first. Missing or ambiguous outlines retain null geometry. Unavailable boundary storage returns 503. Collections retain parent context. Existing Deep access and pooled allowance apply. API 2.0.0 and later.

Default: json

Values: json, geojson

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

Request

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

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.state("BY", { country: "DE" });
console.log(result);
Example responsePaid plan
{
  "state": "BY",
  "iso_code": "DE-BY",
  "fips": null,
  "name": "Bavaria",
  "name_local": "Bayern",
  "type": "land",
  "country": "DE",
  "country_name": "Germany",
  "latitude": 48.946756,
  "longitude": 11.403872,
  "timezones": [
    "Europe/Berlin"
  ],
  "capital": {
    "name": "Munich",
    "latitude": null,
    "longitude": null
  },
  "area_codes": null,
  "population": 13435062,
  "area": 70551
}

iso_code is the full ISO 3166-2 identifier, such as US-CO, or null when unavailable.

Response fields

stateLink to statestring
State or province code
iso_codeLink to iso_codestring or null
Full ISO 3166-2 code (US-CO), or null when unavailable
fipsLink to fipsstring or null
US Census FIPS code. Null outside the US
nameLink to namestring or null
Name
name_localLink to name_localstring or null
Local-language name, null when absent or identical to name
typeLink to typestring or null
State, province, etc.
countryLink to countrystring or null
ISO2 country code
country_nameLink to country_namestring or null
Country name
latitudeLink to latitudenumber or null
Centroid latitude
longitudeLink to longitudenumber or null
Centroid longitude
timezonesLink to timezonesarray or null
Every IANA timezone in the state
capitalLink to capitalobject
Capital city, matching Country’s name, latitude and longitude shape
capital.nameLink to capital.namestring or null
Capital or seat of government name
capital.latitudeLink to capital.latitudenumber or null
Capital latitude; null while only the name is recorded
capital.longitudeLink to capital.longitudenumber or null
Capital longitude; null while only the name is recorded
area_codesLink to area_codesarray or null
Telephone area codes (NANP countries)

Counties in a stateCopy link

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

GET /state/{code}/countiesAPI Explorer ↗

Counties and equivalent areas in a state

Parameters

codestring · path · required

State / province code or name

formatstring · query · optional

json by default. geojson returns simplified administrative Polygon/MultiPolygon outlines with country-qualified IDs and selected facts in properties. Coordinates are longitude first. Missing or ambiguous outlines retain null geometry. Unavailable boundary storage returns 503. Collections retain parent context. Existing Deep access and pooled allowance apply. API 2.0.0 and later.

Default: json

Values: json, geojson

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

Request

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

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.state.counties("nc", { country: "US" });
console.log(result);
Example response
{
  "state": "NC",
  "state_name": "North Carolina",
  "country": "US",
  "country_name": "United States",
  "counties": [
    {
      "county": "37119",
      "iso_code": null,
      "name": "Mecklenburg",
      "type": "county"
    },
    {
      "county": "37063",
      "iso_code": null,
      "name": "Durham",
      "type": "county"
    }
  ]
}

Response fields

stateLink to statestring
State or province code
state_nameLink to state_namestring or null
State or province name
countryLink to countrystring or null
ISO2 country code
country_nameLink to country_namestring or null
Country name
countiesLink to countiesarray
Every county in the state
counties[].countyLink to counties[].countystring or null
County code
counties[].iso_codeLink to counties[].iso_codestring or null
Full ISO 3166-2 code when an exact recorded assignment is available; null otherwise
counties[].nameLink to counties[].namestring or null
County name
counties[].typeLink to counties[].typestring or null
County, department, etc.

GeoJSON state and province outlines

Add format=geojson on API 2.2.0 for a simplified Polygon or MultiPolygon Feature. Its stable id combines the country and state code, such as US-CO. The place facts and included profile fields stay in properties. Coordinates use WGS84 [longitude, latitude].

Choose a place to load its outline.Drag to pan · + / - to zoom
State GeoJSON · HTTP
curl "https://api.parseapi.com/state/CO?country=US&format=geojson" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Version: 2.2.0"
Example

Request

curl "https://api.parseapi.com/state/CO?country=US&format=geojson" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-API-Version: 2.2.0"
Example response
{
  "type": "Feature",
  "id": "US-CO",
  "geometry": {
    "type": "Polygon",
    "coordinates": [
      [
        [
          -102.04,
          36.99
        ],
        [
          -102.05,
          41
        ],
        [
          -109.05,
          41
        ],
        [
          -109.05,
          37
        ],
        [
          -102.04,
          36.99
        ]
      ]
    ]
  },
  "properties": {
    "state": "CO",
    "iso_code": "US-CO",
    "fips": "08",
    "name": "Colorado",
    "name_local": null,
    "type": "state",
    "country": "US",
    "country_name": "United States",
    "area_codes": [
      "303",
      "719",
      "720",
      "970"
    ],
    "capital": {
      "name": "Denver",
      "latitude": null,
      "longitude": null
    },
    "latitude": 38.725178,
    "longitude": -105.607716,
    "timezones": [
      "America/Denver"
    ]
  }
}

/country/US/states?format=geojson returns a FeatureCollection in the existing list order. Parent country context stays on the collection and in each Feature's properties. Collection facts remain the same as the ordinary list. Outline collections are larger than ordinary JSON.

Coverage varies by place. An exact outline that is missing or ambiguous stays geometry: null, even when center coordinates are known. Small islands and holes may be omitted from the simplified display outline. Unavailable boundary storage returns HTTP 503. These are administrative areas. County does not provide electoral constituencies. Outlines do not establish legal borders or survey measurements.

Omit format or use format=json for the ordinary response. Existing profile access and pooled request allowances apply. Use HTTP for GeoJSON. Published SDK and MCP methods retain ordinary JSON. API 1.0.0 is unchanged.

Included dataCopy link

Population, area and tax references. Every plan includes State identifiers, area codes and capital. Included automatically on paid plans in API 2.2.

Paid plan fields

populationLink to populationinteger or null
Population estimate
areaLink to areanumber or null
Total area in km²
tax.nameLink to tax.namestring or null
State or province levy name (Sales tax, HST, GST + PST). Null when unavailable or no levy is named
tax.rateLink to tax.ratenumber or null
State or province reference rate in percent. Choose this geographic reference for state or province tasks

Display languageCopy link

Pass lang with a language tag such as fr, pt-BR, or zh-Hant. Existing country_name and separately sourced state or county 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. Display language is available on API 2.1.0; requests selecting frozen 1.0.0 retain their original contract. See API versions.

33 display language choices

Language tagLanguage
enEnglish
arالعربية
cacatalà
hrhrvatski
csčeština
dadansk
nlNederlands
fisuomi
frfrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
humagyar
idIndonesia
ititaliano
ja日本語
ko한국어
msMelayu
nbnorsk bokmål
plpolski
ptportuguês
roromână
ruрусский
zh-Hans简体中文
skslovenčina
esespañol
svsvenska
thไทย
zh-Hant繁體中文
trTürkçe
ukукраїнська
viTiếng Việt