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/districts?country=US returns the North Carolina list with district codes, names, and types. In API 2.0.0, add &deep=true on a paid plan to include population inside each district's deep:
GET /state/NC/districts?country=US&deep=true
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",
"districts": [
{ "district": "37001", "name": "Alamance County", "type": "county", "deep": { "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 district list and filtering it yourself.
The arrays use names that tell you what their identifiers represent. State options have a state field. District options have a district field. Both have name and type, so a dropdown can use the same presentation with the appropriate identifier as its value.
You can leave deep=true off when that is all the form needs. The State reference describes the additional district detail.
Keep the country code as you move through the form. State codes can repeat across countries, and an empty district list means there are no matching entries in the catalog, not necessarily that the place has no smaller administrative areas.