States · Provinces · Regions

State API

Turn codes and names
into places.

Resolve a state or province to its country, subdivision code and timezones. Build address pickers and location profiles with one API key.

Get startedExplore the API

Try a state code or name

Try it

Example response/state/colorado?deep=true
{
  "state": "CO",
  "iso_subdivision": "US-CO",
  "fips": "08",
  "name": "Colorado",
  "name_local": null,
  "type": "state",
  "country": "US",
  "country_name": "United States",
  "latitude": 38.725178,
  "longitude": -105.607716,
  "timezones": ["America/Denver"],
  "area_codes": ["303", "719", "720", "970"],
  
    "name": "Denver",
    "latitude": null,
    "longitude": null
  },
  ?deep=true
    "population": 5957493,
    "area": 269837,
    
      "name": "Sales tax",
      "rate": 2.9
    }
  }
}

From input to integration

Codes for your app.
Names for your customers.

Look up a place, load a selector or add a profile. Choose a task to see its request and complete JSON response.

A name becomes a place.

Colorado resolves by name to its state code, country, coordinates and IANA timezones. Keep the codes for your records and the names for your interface.

Request

curl "https://api.parseapi.com/state/colorado?deep=true" \
  -H "X-API-Key: YOUR_API_KEY"

Example response

JSON200 OK
{
  "state": "CO",
  "iso_subdivision": "US-CO",
  "fips": "08",
  "name": "Colorado",
  "name_local": null,
  "type": "state",
  "country": "US",
  "country_name": "United States",
  
    "name": "Denver",
    "latitude": null,
    "longitude": null
  },
  
    "303",
    "719",
    "720",
    "970"
  ],
  "latitude": 38.725178,
  "longitude": -105.607716,
  
    "America/Denver"
  ],
  
    "population": 5957493,
    "area": 269837,
    
      "name": "Sales tax",
      "rate": 2.9
    }
  }
}

Country and state dropdowns

Every choice.
Connected.

Choose a country, load its states, then list the selected state's counties or districts. Use each area's type to label the next address field.

Build the dropdown flow
  1. 01

    Choose a country

    /country

    Country codes and names for the first picker.

  2. 02

    Load its states

    /country/US/states

    US subdivision codes, names and types. Select Delaware with its DE code.

  3. 03

    Load its counties or districts

    /state/DE/districts?country=US

    Delaware returns county codes and names for the next field. The API uses districts for this level and type for the local name. Lists cover the US, France and Great Britain.

GeoJSON outlines

Draw the place.

Put state and province boundaries on your map.

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 "Parse-Version: 2.0.0"

GeoJSON reference

Optional Deep

Give the place
some context.

Add population and area to a regional profile, or the capital to a directory. Deep adds available detail to the same lookup.

/state/colorado?deep=true

Colorado, United States
Population
5,957,493
Total area
269,837 km2
Capital
Denver

Add form.js to your fields

Keep the state picker with its country.

Use form.js to load states and provinces into your own dropdown. Store the selected state code alongside the country code from the first field.

Try connected dropdowns

Include the script once with your website's domain-restricted public key. Use these bindings in your existing form.

Your form · HTML
<script src="https://cdn.parseapi.com/v1/form.js"
        data-key="parse_public_YOUR_KEY" defer></script>

<label for="form-country">Country</label>
<select id="form-country" name="country" data-parse="country">
  <option value="">Choose a country</option>
  <option value="US">United States</option>
  <option value="CA">Canada</option>
  <option value="GB">United Kingdom</option>
</select>

<label for="form-state">State or province</label>
<select id="form-state" name="state"
        data-parse-from="form-country" data-parse-fill="states">
  <option value="">Choose a state or province</option>
</select>

From the example to your application

One key.
Your whole place flow.

Send a name or code over HTTP, or call State from your SDK. Country supplies state lists, and District resolves the county codes returned by State.

HTTP, SDKs and MCP

Copy a request above, use your language's SDK, or bring State lookups to your agent through MCP.

State referenceCountry listsDistrict lookupsExplore MCP

Before you build.

Which places does the State API cover?

State looks up recorded administrative subdivisions, including states, provinces, territories, regions and prefectures. The coverage table groups countries with subdivision records by continent. Available coordinates, timezones and profile facts vary by place; missing facts remain null.

Do I need to pass a country?

A globally unique name or code can resolve on its own, such as /state/colorado. For a shared code, add country: /state/CA?country=US selects California. Country accepts an ISO2 code, ISO3 code or name. Ambiguous and missing places return 404 with guidance.

How do I build country and state dropdowns?

Use GET /country for countries, then GET /country/{code}/states for the selected country’s recorded subdivisions. Each row contains state, name and type. Keep the country and state codes together, then use /state/{code}?country={country} for the selected place.

Can I list the counties or districts in a state?

Yes. GET /state/{code}/districts?country={country} lists the recorded areas within a state. The API calls this level districts; type gives the local name, such as county. Coverage includes the US, France and Great Britain. A state without recorded areas returns an empty list. Paid Deep adds available population to each area.

What does Deep add to a state lookup?

On a paid plan, add deep=true for available population, total area in square kilometers and the tax reference. Core includes the capital, US FIPS and telephone area codes. The ordinary fields stay unchanged. Free returns the ordinary answer with deep: {}.

How should I use coordinates and timezones?

Coordinates describe the subdivision center. timezones lists the recorded IANA zones. A state can span more than one timezone. Use Point for the timezone at a specific coordinate.

Can I show translated or native names?

name_local holds the native name when it differs from the original display name, such as Bayern for Bavaria. Pass lang to request a supported display language for names. Codes, coordinates and native names keep their values; missing translations use the existing label.

What does the tax rate represent?

Paid Deep returns a geographic reference rate in percent where available. Country, state and postal rates are alternative references; a state rate may already include national tax. US Postal provides a combined ZIP reference. Missing reference facts stay null.

How is State priced?

Each lookup, state-list request or district-list request uses one API request from your shared ParseAPI allowance. Ordinary lookups and lists work on every plan. Deep is included on paid plans in the same request, with no additional per-field or per-record charge.

State API pricing

Put places
in your app.

Start free with state lookups and lists. Add Deep profiles on a paid plan. Your API request allowance is shared across ParseAPI products.

Free

Start with a free API key.

State lookups and lists

Room to grow

Choose your capacity on Plans.

Lookups, lists and Deep profiles

Get startedCompare plans