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.

LookupCopy link

GET /address/{address}API Explorer ↗

US address in, valid + registered + standardized parts out

Parameters

addressstring · path · required

Freeform US address, URL-encoded

countrystring · query · optional

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

Example

Request

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

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.address("152 200th Avenue, Ellsworth MN");
console.log(result);
Example response
{
  "address": "152 200th Avenue, Ellsworth, MN 56129",
  "valid": true,
  "registered": true,
  "number": "152",
  "street": "200th Avenue",
  "unit": null,
  "postal": "56129",
  "city": "Ellsworth",
  "county": "27105",
  "county_name": "Nobles",
  "state": "MN",
  "state_name": "Minnesota",
  "country": "US",
  "country_name": "United States",
  "latitude": 43.506772,
  "longitude": -96.073118
}

Response fields

addressLink to addressstring or null
Standardized address line
validLink to validboolean
Input parses as a US address. Junk returns valid: false on a 200, never a 404
registeredLink to registeredboolean or null
Matches official records, including mapped street-number ranges. Null for missing coverage. Not a deliverability claim
numberLink to numberstring or null
House number
streetLink to streetstring or null
Standardized street line
unitLink to unitstring or null
Unit as given. registered reflects the building when the records have no unit rows
postalLink to postalstring or null
US ZIP code
cityLink to citystring or null
City name
countyLink to countystring or null
County code (US county FIPS)
county_nameLink to county_namestring or null
County name
stateLink to statestring or null
State code
state_nameLink to state_namestring or null
State name
countryLink to countrystring or null
ISO2 country code (US)
country_nameLink to country_namestring or null
Country name
latitudeLink to latitudenumber or null
Published registry latitude; null for range matches or absent coordinates
longitudeLink to 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. This lookup has no additional profile fields.

AutocompleteCopy link

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 /address?q={partial}API Explorer ↗

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

Parameters

qstring · query · required

The partial address as typed

countrystring · query · optional

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

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.

Request

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

const parse = parseAPI("YOUR_API_KEY");
const result = await parse.address.search("200th", { postal: "56129" });
console.log(result);
Example response
{
  "q": "200th",
  "postal": "56129",
  "addresses": [
    {
      "address": "152 200th Avenue, Ellsworth, MN 56129",
      "number": "152",
      "street": "200th Avenue",
      "unit": null,
      "postal": "56129",
      "city": "Ellsworth",
      "state": "MN",
      "latitude": 43.506772,
      "longitude": -96.073118
    },
    {
      "address": "222 200th Avenue, Ellsworth, MN 56129",
      "number": "222",
      "street": "200th Avenue",
      "unit": null,
      "postal": "56129",
      "city": "Ellsworth",
      "state": "MN",
      "latitude": 43.517176,
      "longitude": -96.073233
    },
    {
      "address": "421 200th Avenue, Ellsworth, MN 56129",
      "number": "421",
      "street": "200th Avenue",
      "unit": null,
      "postal": "56129",
      "city": "Ellsworth",
      "state": "MN",
      "latitude": 43.54581,
      "longitude": -96.073278
    }
  ],
  "reason": null
}

Response fields

qLink to qstring
The partial input as typed
postalLink to postalstring or null
Echoed ZIP scope (when passed)
cityLink to citystring or null
Echoed city scope (when passed)
stateLink to statestring or null
Echoed state scope (when passed)
addressesLink to addressesarray
Ranked suggestions, same parts as lookup
addresses[].numberLink to addresses[].numberstring or null
House number. Null on street-grain rows, a number appears only when it exists in the records
reasonLink to 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.