Blog·Craft·

County, department, or district

The district endpoint keeps a consistent response while type tells you what kind of administrative area it describes.

A US county and a French department can occupy the same field in an application without being renamed to the same thing. That's why /district returns both a consistent set of fields and a type.

Compare these response excerpts.

GET /district/37081:

{ "district": "37081", "name": "Guilford County", "type": "county", "country": "US" }

GET /district/75:

{ "district": "75", "name": "Paris", "type": "department", "country": "FR" }

GET /district/E09000001:

{ "district": "E09000001", "name": "City and County of the City of London", "type": "district", "country": "GB" }

Your application reads district for the code and name for the label in each case. When the kind of area matters to the display, type supplies it. There's no need for a separate response parser for each country.

The codes themselves come from the country's system: US FIPS, French INSEE, or British GSS in these examples. Keep them as strings so leading zeros and letters survive.

These three lookups resolve without a country parameter. That doesn't make district codes globally unique. Pass ?country= when you have the country. If a code is ambiguous, the API asks for it instead of picking a record.