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.
Try a state code or name
Try it
Highlighted fields: Included on paid plans.
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" \
-H "X-API-Key: YOUR_API_KEY" \
-H "X-API-Version: 2.2.0"Example response
Highlighted fields: Included on paid plans.
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- 01
Choose a country
/country
Country codes and names for the first picker.
- 02
Load its states
/country/US/states
US subdivision codes, names and types. Select Delaware with its DE code.
- 03
Load its counties or districts
/state/DE/counties?country=US
Delaware returns county codes and names for the next field. The API uses counties 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.
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"Included on paid plans
Give the place
some context.
Add population, area and tax references to a regional profile. Core includes the capital and identifiers.
/state/colorado
- Population
- 5,957,493
- Total area
- 269,837 km2
Add form.js to your fields
Choose a state. Load its counties.
Use form.js to connect your country, state and county fields. Changing a parent clears the old choices below it. Your form stores the codes and shows the names.
County lists cover the US, France and Great Britain. The Form demo also shows editable inputs with suggestions for manual entry.
Try connected dropdownsInclude the script once with your website's domain-restricted public key. Use these bindings in your existing form.
- Country
- United States
US - State or province
- Delaware
DE - County or district
- Kent County
10001
Country → State → County. Show names and save codes.
Add form.js to these fields
<script src="https://cdn.parseapi.com/v1/form.js?v=c18e1976f5b8"
data-key="parse_public_YOUR_KEY" data-parse-version="2.2.0" 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>
<option value="FR">France</option>
</select>
<label for="form-state">State or province</label>
<select id="form-state" name="state" data-parse="state"
data-parse-from="form-country" data-parse-fill="states">
<option value="">Choose a state or province</option>
</select>
<label for="form-district">County or district</label>
<select id="form-district" name="county"
data-parse-from="form-state" data-parse-fill="counties">
<option value="">Choose a county or district</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 County 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.
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}/counties?country={country} lists the recorded areas within a state. The API calls this level counties; type gives the local name, such as county or department. Coverage includes the US, France and Great Britain. A state without recorded areas returns an empty list. Paid plans automatically include available population on each area.
What do paid plans include?
Paid plans automatically include 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 complete ordinary answer without the paid detail.
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 plans include 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 county-list request uses one API request from your shared ParseAPI allowance. Ordinary lookups and lists work on every plan. Paid profile detail is included automatically 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. Paid plans include the available profile detail automatically. 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 paid profiles