Reverse Address API

Overview

Identify, enhance, and update records from a single data attribute. Leverage over 30+ years of address history, 600M+ phone-to-person matches, 275M unique person-to-address matches, and more. A Reverse Address request allows you to find all the information about a location in the Whitepages databases. Using a RESTful GET API request, you’ll receive every record related to the address given.

Get a Free API Key Not a developer?

Request

A well-formatted request looks like:

Copy
https://proapi.whitepages.com/3.0/location?street_line_1=1301+5th+ave+ste+1600&city=Seattle&postal_code=98101&state_code=WA&api_key=KEYVAL

All parameters are case sensitive. api_key, a street parameter, and either zip or state is required for a Reverse Location Request.

REQUEST PARAMETERS

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

2808 Nero Blvd

street_line_2Apartment or other additional address information

Apt 265, Box 34Rs

cityCity name

Seattle, New York

postal_code5 or 9 digit US or 6 digit Canadian zip code

92019 or S3D 3F3

state_code2 character state code

WA

country_code2 character country code

CA or US

Response

A Reverse Address response is formatted as follows.

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

Reverse Address Response

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

Normalized input address id. Could be used to check if multiple input addresses are actually identical.

2is_validBoolean

Copy
"is_valid": true
Boolean value indicating if 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

Not used. Reserved.

5cityString

Copy
"city": "Seattle"

Normalized city name. Example: “Olympia”.

6postal_codeString

Copy
"postal_code": "98101"
5-digit US or 6 digit Canadian zipcode. Example: “98101” or “S3D 3F3”.

7zip4String

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

8state_codeString
Copy
"state_code": "WA"

2 character US state/territory code (ISO 3166-2:US) or Canadian province code (ISO 3166-2:CA). Examples: “WA” for Washington or “BC” for British Columbia.

9country_codeString

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

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

11is_activeBoolean
Copy
"is_active": true

Indicates if the address is valid and currently receiving mail. Possible values are true, false, or null.

If false, USPS cannot deliver to this address or this address is not receiving mail currently.

12delivery_pointString
Copy
"delivery_point": "SingleUnit"

Only valid for US addresses. Indicates the type of mailbox associated with the address. One of:

  • CommercialMailDrop
  • POBoxThrowback
  • POBox
  • MultiUnit
  • SingleUnit
13last_sale_dateString
Copy
"last_sale_date": "2015-05-07"

Only valid for US addresses. Shows the date of the last sale.

14total_valueInteger
Copy
"total_value": 355000

Only valid for US addresses. Shows total assessed tax value of the property in USD.

15ownersArray

Only valid for US addresses. List of current property owners.

idString
Copy
"id""Business.88e44955-805c-455a-99da-d7444ca5c484.Durable"

Person or Business id of the property owner.

nameString
Copy
"name""Whitepages"

Full Business or Person name.

firstnameString
Copy
"firstname"null

Person’s first name. Only applicable to person entities. Always null for Business.

middlenameString
Copy
"middlename": null

Person’s middle name. Only applicable to person entities. Always null for Business.

lastnameString
Copy
"lastname": null

Person’s last name. Only applicable to person entities. Always null for Business.

age_rangeString
Copy
"age_range": null

Person’s age range. Only applicable to person entities. Always null for Business.

Possible values are: 18-24, 25-29, 30-34, 35-39, 40-44, 45-49, 50-54, 55-59, 60-64, 65-69, 70-74, 75-79, 80-84, 85-89, 90+.

genderString
Copy
"gender": null

Person’s gender. Only applicable to person entities. Always null for Business. Possible values are Female, Male, null.

typeString
Copy
"type": Business

Type of the property owner. Possible values: Business, Person.

16current_residentsArray

Array of objects describing business and people residents. See below for exact structure.

idString
Copy
"id": "Business.7e29cf66-8bf2-4812-829d-356654b5b3d3.Durable" 

Business or Person entity id currently linked to input address.

nameString
Copy
"name": "Whitepages"

Full Business or Person name.

firstnameString
Copy
"firstname": null

Person’s first name. Only applicable to person entities. Always null for Business.

middlenameString
Copy
"middlename": null

Person’s middle name. Only applicable to person entities. Always null for Business.

lastnameString
Copy
"lastname": null

Person’s last name. Only applicable to person entities. Always null for Business.

age_rangeString
Copy
"age_range": null 

Person’s age range. Only applicable to person entities. Always null for Business. Possible returns include: 18-24, 25-29, 30-34, 35-39, 40-44, 45-49, 50-54, 55-59, 60-64, 65-69, 70-74, 75-79, 80-84, 85-89, 90+.

genderString
Copy
"gender": null 

Person’s gender. Only applicable to person entities. Always null for Business. Possible values are Female, Male, null.

typeString
Copy
"type": Business

Type of entity linked to the address. Possible values are Business, Person.

phonesArray
Copy
"phones": [
{
"id": "Phone.4d796fef-a2df-4b08-cfe3-bc7128b6f6bb.Durable",
"phone_number": "+12069735100"
}
]

Array of phones linked to the person or business. Objects contain an id string and phone_number sting in international (E.164) format.

associated_peopleArray
Copy
"associated_people": [ ]

Array of associated people objects contain an id string, full name string, and relation status string.

link_to_address_start_dateString
Copy
"link_to_address_start_date": null

ISO format date string indicating when person or business got linked to the address.

17warningsArray
Copy
"warnings": [ ]

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

  • Invalid Input
  • Missing Input
  • Partial Address
  • Invalid Country Code
  • Missing unit/apt/suite number
  • Invalid unit/apt/suite number
  • Input postal code was corrected. Potential impact to AVS code.
18errorObject
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.Durable",
"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"
},
"is_active": true,
"delivery_point": "MultiUnit",
"last_sale_date": null,
"total_value": null,
"owners": [ ],
"current_residents": [
{
"id": "Business.7e29cf66-8bf2-4812-829d-356654b5b3d3.Durable",
"name": "Whitepages",
"firstname": null,
"middlename": null,
"lastname": null,
"age_range": null,
"gender": null,
"type": "Business",
"link_to_address_start_date": null,
"phones": [
{
"id": "Phone.4d796fef-a2df-4b08-cfe3-bc7128b6f6bb.Durable",
"phone_number": "+12069735100"
},
{
"id": "Phone.345f6fef-a2e1-4b08-cfe3-bc7128b7ba13.Durable",
"phone_number": "+18003361327"
}
],
"associated_people": []
}
],
"warnings": [],
"error": null
}