Blog·Craft·

Lists give you a code and a name

Country, state, and district lists pair a readable name with the code you need for the next lookup.

A location picker needs two things from each option: a name to show the person and a code to save or send in the next request.

The country, state, and district lists follow that pattern. Here is a selected row from each response, with unrelated fields omitted.

From /continent/na/countries:

{ "country": "CA", "name": "Canada" }

From /country/us/states:

{ "state": "NC", "name": "North Carolina", "type": "state" }

From /state/nc/districts?country=US:

{ "district": "37001", "name": "Alamance County", "type": "county" }

name is always the display label. The code field is named for what it identifies: country, state, or district. These aren't identical objects, and your picker does need to know which code field it is reading. But the job is consistent at each level.

That matters when the form gets more specific. After someone picks North Carolina, you can pass NC into the district-list request instead of trying to turn the displayed name back into a code. Keep the country alongside it so a state code isn't ambiguous.

The lists live in named arrays (countries, states, and districts) in their responses. State and district rows also include type, so a UI can distinguish a state from a province or a county from another kind of district.