Required plan

Available in all plans

@typeStringEither one of 'home’, 'work’ or 'old’. Default is 'home’
countryStringAlpha-2 ISO 3166 country code
stateString2 letters state code, if country is one of US, Canada or Brazil. 3 letters state code if country is Australia or UK.
cityStringCity name
streetStringStreet name
houseStringHouse number
apartmentStringApartment number
zip_codeStringPostal zip code
po_boxStringPost Office box number
rawStringAn unparsed full address. Request only.
displayStringThe full address for display purposes. Response only.

Search Requirements

The minimal requirement for an address to be helpful in a search is that it must contain a known country. If you provide only a city or state, we will try to complete the rest of the information.

For an address to be sufficient for a search as the single parameter, it must be a valid US address and contain a street, house number, city, and state. Please note that it is not possible to search by multiple addresses as the only parameters or to search by non-US addresses.

Raw Address Parsing

When you don’t know the breakdown of an address string to its components, don’t worry. Just fill in the raw member of the address object and we will do the parsing for you.

To see the final result of the parsing, take a look at the query member of the response object. It holds the final person that we have searched for.


    "@valid_since": "1999-02-01", 
    "country": "US", 
    "state": "KS", 
    "city": "Smallville", 
    "street": "Hickory Lane", 
    "house": "10", 
    "apartment": "1", 
    "zip_code": "66605", 
    "display": "10-1 Hickory Lane, Smallville, Kansas"