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
}

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("99999 N Elm St 27401");
console.log(result);

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

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

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("purple monkey dishwasher");
console.log(result);

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

Example response
{
  "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
Matches official records, including mapped street-number ranges. Null for missing coverage. 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
US ZIP code
country
ISO2 country code (US)
country_name
Country name
latitude
Published registry latitude; null for range matches or absent coordinates
longitude
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
{
  "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
  ],
  "reason": null
}

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
reason
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