Looking up a street address

An address field gives you a string. The useful part is turning it into a street, city, state, and postal code, then finding out whether it matches an official address record.

/address takes the whole string, so you can pass along what someone entered in a form. Here is a US example, shortened to show the standardized address and the two checks:

GET /address/152 200th Avenue, Ellsworth MN

{
  "address": "152 200th Avenue, Ellsworth, MN 56129",
  "valid": true,
  "registered": true,
  "number": "152",
  "street": "200th Avenue",
  "city": "Ellsworth",
  "state": "MN",
  "postal": "56129",
  "country": "US"
}

valid tells you the input parsed as an address. registered is the separate result from checking official records. An address can pass the first check without passing the second, so these need to be separate fields.

The full response also includes county information and coordinates when available. An apartment or suite number supplied in the input stays in unit. A registration match does not establish postal deliverability to that unit.

Malformed input returns a normal response with valid: false. If the lookup cannot establish a registration answer, registered is null. Your form can use those results to ask for more information without throwing away the address the person already entered.