Blog·Craft·

One code, three routes

The district code from a coordinate or postal lookup can be used directly to retrieve the county record.

If you start with coordinates, you shouldn't need a different county identifier than someone who starts with a ZIP code. Both lookups need to lead to the same county record.

For example, a point in Greensboro returns Guilford County's code. These are the relevant fields:

GET /point?lat=36.0726&lon=-79.792
{
  "country": "US",
  "state": "NC",
  "district": "37081",
  "district_name": "Guilford"
}

Pass that district value to /district/37081?country=US and you get the Guilford County record, including its full name. Add &deep=true on a paid plan for available statistics.

A postal lookup uses the same field. These excerpts show a ZIP code in Miami-Dade and the county lookup it leads to:

GET /postal/33139?country=US
{ "district": "12086", "district_name": "Miami-Dade" }
GET /district/12086?country=US
{ "district": "12086", "name": "Miami-Dade County", "type": "county" }

The labels can differ because one response uses a short county name and another uses the full name. The code is what connects them.

If your app caches district records by country and code, it can reuse a record whether /point or /postal supplied the code first. There is no translation table to maintain between those endpoints. Keep the codes as strings, including any leading zeroes.