Search by task, endpoint, field, or error.

← Docs

Address API

A US address, checked against official 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.

registered means a match in official records. US matches can also come from mapped street-number ranges, which return null coordinates. A scope outside the published record set returns null. This does not establish postal deliverability or confirm a supplied apartment.

Lookup

GET
api.parseapi.com/address/{address}
US address in, valid + registered + standardized parts out
Explore
Parameters 2
countrystring · query · optional

Address country. Current published coverage is US; defaults to US.

addressstring · path · required

Freeform US address, URL-encoded

Run uses the free demo on API 2.0.0. Copied code uses your API key when signed in, or YOUR_API_KEY when signed out.

SDK quickstart
import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.address("152 200th Avenue, Ellsworth MN");
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response
{
  "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
}

Response fields

addressstring or null
Standardized address line
validboolean
Input parses as a US address. Junk returns valid: false on a 200, never a 404
registeredboolean or null
Matches official records, including mapped street-number ranges. Null for missing coverage. Not a deliverability claim
numberstring or null
House number
streetstring or null
Standardized street line
unitstring or null
Unit as given. registered reflects the building when the records have no unit rows
citystring or null
City name
districtstring or null
District code (US county FIPS)
district_namestring or null
District name
statestring or null
State code
state_namestring or null
State name
postalstring or null
US ZIP code
countrystring or null
ISO2 country code (US)
country_namestring or null
Country name
latitudenumber or null
Published registry latitude; null for range matches or absent coordinates
longitudenumber or null
Published registry longitude; null for range matches or absent coordinates

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

Autocomplete

For the US, 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
Explore
Parameters 6
countrystring · query · optional

Address country. Current published coverage is US; defaults to US.

qstring · query · required

The partial address as typed

postalstring · query · optional

Postal code scope from the form

citystring · query · optional

City scope; pair with state for the US

statestring · query · optional

US state code

ipstring · query · optional

End-user IP for ranking bias when calling server-side

reason is null when suggestions exist. more_input asks for more street input; missing_context asks for a ZIP or city and state; no_matches means the search completed without a match. A search service failure returns 503. Keep a fallback for future reason values.

Run uses the free demo on API 2.0.0. Copied code uses your API key when signed in, or YOUR_API_KEY when signed out.

SDK quickstart
import { parseAPI } from '@parseapi/sdk';

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.address.search("200th", { postal: "56129" });
console.log(result);

Run on your server with a secret key. Calling from a browser or app?

Example response (excerpt)

This example shows selected fields or shortened lists. Run the request for the full response.

{
  "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
    }
  ],
  "reason": null
}

Response fields

qstring
The partial input as typed
postalstring or null
Echoed ZIP scope (when passed)
citystring or null
Echoed city scope (when passed)
statestring or null
Echoed state scope (when passed)
addressesarray
Ranked suggestions, same parts as lookup
addresses[].numberstring or null
House number. Null on street-grain rows, a number appears only when it exists in the records
reasonstring or null
Null when suggestions exist. more_input asks for more street input; missing_context asks for a postal code or city and state; no_matches means the completed search found nothing. Additional reasons may be added. Unavailable search services return 503.

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.

Build with Address

All tutorials →

Questions? Email