Global Address Validation API

Normalize and verify addresses in 170+ countries

This global API provides the ability to:
• Parse and normalize inputs
• Validate and geocode addresses
• Get a unique identifier (UUID) for every address

Get a Free API Key Not a developer?

Request

A well-formatted request looks like:

Copy
https://proapi.whitepages.com/3.1/location_intel?street_line_1=1301+5th+ave&street_line_2=ste+1600&city=Seattle&postal_code=98101&state_code=WA&country_code=US&api_key=KEYVAL

All parameters are case sensitive. api_key, a street parameter, and either zip or state is required for a Address Validation request.

REQUEST PARAMETERS

PARAMETERSDESCRIPTIONEXAMPLES
api_keySee here to acquire an API key REQUIRED
street_line_1Number and street name

1301 5th Ave

street_line_2Apartment or other additional address information

ste 1600

cityCity name

Seattle

postal_codeAddress postal code in location country format

98101

state_codeAddress state / administrative area name or code in location country format

WA

country_codeCountry code or name. If there is no country_code in the request address will be tried against US and CA country codes by default.

US

Response

An Address Validation response is formatted as follows.

Click the # to see that field used within the example JSON response.

Address Validation Response

1idString
Copy
"id": "Location.88e44955-805c-455a-99da-d7444ca5c484"

Normalized permanent input address id. Could be used to check if multiple input addresses are actually identical. A durable id will always be returned if the input is valid.

2is_validBoolean

Copy
"is_valid": true
Boolean value indicating if input address is valid. Possible values are:

  • true
  • false
  • null
3street_line_1String
Copy
"street_line_1": "1301 5th Ave Ste 1600"

Normalized and validated street_line_1. Contains both primary and the optional secondary address data.

4street_line_2String

Copy
"street_line_2": null

Normalized sub premise part of the address. This field may vary depending on a country.

5cityString

Copy
"city": "Seattle"

Normalized city name. Example: “Olympia”.

6postal_codeString

Copy
"postal_code": "98101"
Postal code for the address in specified country location. Example: “98101” in US or “S3D 3F3” in CA.

7zip4String

Copy
"zip4": "4206"
4-digit US zipcode extension.

8state_codeString
Copy
"state_code": "WA"

State or administrative area for the address in the country location. Examples: “WA” for Washington in US or “BC” for British Columbia in CA.

9country_codeString

Copy
"country_code": "US"
Country code (ISO 3166-1 alpha-2) or country name, Example: “US” or “Mexico”.

10lat_longObject

Latitude and longitude associated with the returned address. Includes “accuracy” string that represents the accuracy of the latitude/longitude with levels decreasing in precision in the following order: RoofTop, Street, PostalCode, Neighborhood, City, State, Country.

latitudeString

Copy
"latitude": 47.707649
Decimal latitude

longitudeString

Copy
"longitude": -122.212463
Decimal longitude

accuracyString

Copy
"accuracy": "RoofTop"
Represents the qualitative accuracy of the lat-long for the location. One of: RoofTop, Street, PostalCode, Neighborhood, City, State, Country

11warningsArray
Copy
"warnings": [ ]

An array containing one or more of the following warning message strings:

  • House number not validated
  • City, Country Validated
  • Input postal code was corrected. Potential impact to AVS code.
  • Invalid Country Code
  • In US/CA only:

  • Missing unit/apt/suite number
  • Invalid unit/apt/suite number
12input_completenessArray
Copy
"input_completeness": "Complete"

An array indicating whether a full address including line 1 was present in the request or only partial input (city level) was provided. Possible response message strings:

  • Complete
  • Address line 1 and location provided

  • Partial
  • Only location (city, state, postal code) provided

  • Empty
  • Only country provided

  • Missing
  • No input fields

13errorObject
Copy
"error": null

An error object which contains name string and message string. For example:

Copy
{
"message": "Could not retrieve entire response",
"name": "PartialError"
}

OR

Copy
{
"message": "International Address Lookup not authorized",
"name": "AuthError"
}

Response

Copy
{
"id": "Location.88e44955-805c-455a-99da-d7444ca5c484",
"is_valid": true,
"street_line_1": "1301 5th Ave Ste 1600",
"street_line_2": null,
"city": "Seattle",
"postal_code": "98101",
"zip4": null,
"state_code": "WA",
"country_code": "US",
"lat_long": {
"latitude": 47.608624,
"longitude": -122.334442,
"accuracy": "RoofTop"
},
"warnings": [],
"input_completeness": "Complete",
"error": null
}