Address API

A US address, checked against official government records.

Look up a US address as one freeform string, the way a form gave it to you. Back come valid, registered, and the standardized parts: number, street, unit, city, county, state, ZIP, and the registry coordinates.

The records are the US DOT National Address Database, about 90 million address points compiled from state and local 911 authorities. registered means the address exists in those records. It is not USPS deliverability. Coverage follows the records ZIP by ZIP: where they stop, registered answers null, never a guess.

Lookup

GET

api.parseapi.com/address/{address}

Freeform US address in, valid + registered + standardized parts out

curl "https://api.parseapi.com/address/152%20200th%20Avenue%2C%20Ellsworth%20MN" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "address": "152 200th Avenue, Ellsworth, MN 56129",
  "valid": true,
  "registered": true,
  "number": "152",
  "street": "200th Avenue",
  "unit": null,
  "city": "Ellsworth",
  "district": "27105",
  "district_name": "Nobles",
  "state": "MN",
  "state_name": "Minnesota",
  "postal": "56129",
  "country": "US",
  "country_name": "United States",
  "latitude": 43.506772,
  "longitude": -96.073118
}

curl "https://api.parseapi.com/address/99999%20N%20Elm%20St%2027401" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "address": "99999 N Elm St, Greensboro, NC 27401",
  "valid": true,
  "registered": false,
  "number": "99999",
  "street": "N Elm St",
  "unit": null,
  "city": "Greensboro",
  "district": "37081",
  "district_name": "Guilford",
  "state": "NC",
  "state_name": "North Carolina",
  "postal": "27401",
  "country": "US",
  "country_name": "United States",
  "latitude": null,
  "longitude": null
}

curl "https://api.parseapi.com/address/purple%20monkey%20dishwasher" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "address": "purple monkey dishwasher",
  "valid": false,
  "registered": null,
  "number": null,
  "street": null,
  "unit": null,
  "city": null,
  "district": null,
  "district_name": null,
  "state": null,
  "state_name": null,
  "postal": null,
  "country": "US",
  "country_name": "United States",
  "latitude": null,
  "longitude": null
}

Response fields

address: Standardized address line
valid: Input parses as a US address. Junk returns valid: false on a 200, never a 404
registered: Address exists in official government records. True or false only where the records cover the area, null when they do not. Not a deliverability claim
number: House number
street: Standardized street line
unit: Unit as given. registered reflects the building when the records have no unit rows
city: City name
district: District code (US county FIPS)
district_name: District name
state: State code
state_name: State name
postal: 5-digit ZIP
country: ISO2 country code (US for now)
country_name: Country name
latitude: Registry point latitude (null when not registered)
longitude: Registry point longitude (null when not registered)

Units pass through and match registry unit rows when they exist. registered reflects the building. ?deep=true returns deep: {}, reserved.

Autocomplete

Ranked suggestions from the same records. Pass ?postal= or ?city=&state=from the form when you have them. Without them, the caller's IP sets the search state and ranks the home city first. Browser calls on a public key carry the visitor's IP automatically, server-side proxies should forward ?ip=. IP bias only ranks: a wrong city reorders suggestions, it never hides a street.

GET

api.parseapi.com/address?q={partial}

Autocomplete. Scope with ?postal= or ?city=&state=, ?ip= server-side

curl "https://api.parseapi.com/address?q=200th&postal=56129" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "q": "200th",
  "postal": "56129",
  "addresses": [
    {
      "address": "152 200th Avenue, Ellsworth, MN 56129",
      "number": "152",
      "street": "200th Avenue",
      "unit": null,
      "city": "Ellsworth",
      "state": "MN",
      "postal": "56129",
      "latitude": 43.506772,
      "longitude": -96.073118
    },
    {
      "address": "222 200th Avenue, Ellsworth, MN 56129",
      "number": "222",
      "street": "200th Avenue",
      "unit": null,
      "city": "Ellsworth",
      "state": "MN",
      "postal": "56129",
      "latitude": 43.517176,
      "longitude": -96.073233
    },
    {
      "address": "421 200th Avenue, Ellsworth, MN 56129",
      "number": "421",
      "street": "200th Avenue",
      "unit": null,
      "city": "Ellsworth",
      "state": "MN",
      "postal": "56129",
      "latitude": 43.54581,
      "longitude": -96.073278
    },
    // ... 2 more
  ]
}

Response fields

q: The partial input as typed
postal: Echoed ZIP scope (when passed)
city: Echoed city scope (when passed)
state: Echoed state scope (when passed)
addresses: Ranked suggestions, same parts as lookup
addresses[].number: House number. Null on street-grain rows, a number appears only when it exists in the records

Suggestions never invent a house number. A number appears only when it exists in the records. A street without a confirmed number suggests at street grain, number: null.

Questions? Email