BlogFormsUpdated

A state carries its own counties list

Fetch the counties within a state using the state and country codes your application already has.

After a form has a country and state, it may need one more list: counties in North Carolina, for example, or departments in a French region.

GET /state/NC/counties?country=US returns the North Carolina list with county codes, names, and types. In API 2.2.0, paid plans also include available population on each county:

GET /state/NC/counties?country=US
X-API-Version: 2.2.0

This excerpt shows the first entry, keeping the population figure from the original example:

{
  "state": "NC",
  "state_name": "North Carolina",
  "country": "US",
  "country_name": "United States",
  "counties": [
    {
      "county": "37001",
      "name": "Alamance County",
      "type": "county",
      "population": 183040
    }
  ]
}

It's the same navigation pattern as /country/{code}/states. Start with the selected parent's code and ask for its children, rather than searching a global county list and filtering it yourself.

The arrays use names that tell you what their identifiers represent. State options have a state field. County options have a county field. Both have name and type, so a dropdown can use the same presentation with the appropriate identifier as its value.

Use those identifiers and labels for the dropdown even when the response includes additional fields. The State reference describes the available county detail.

Keep the country code as you move through the form. State codes can repeat across countries, and an empty county list means there are no matching entries in the catalog, not necessarily that the place has no smaller administrative areas.