👍

Required plan

Available in all plans

Component

Type

Description

@type

String

Either one of 'home’, 'work’ or 'old’. Default is 'home’

country

String

Alpha-2 ISO 3166 country code

state

String

2 letters state code, if country is one of US, Canada or Brazil. 3 letters state code if country is Australia or UK.

city

String

City name

street

String

Street name

house

String

House number

apartment

String

Apartment number

zip_code

String

Postal zip code

po_box

String

Post Office box number

raw

String

An unparsed full address. Request only.

display

String

The 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.

Example

{
    "@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"
}