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/2.2/location.json?city=ashland&postal_code=59004&state=mt&street_line_1=3023+Hansberry+Ave&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. You can also create a request with the lat, lon, radius, and an API key.

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

92019 or S3D 3F3

postal_code5 or 9 digit US or 6 digit Canadian zip code

92019 or S3D 3F3

state_code2 character state code

WA

country_codeNormalized 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

1idID

Copy
"id":{
"key":"Location.2e429fc8-ca9e-4c8c-a79b-c702de43bc2a.Durable",
"type":"Location"
}
The Whitepages entity id.

2typeString

Copy
type: "Address"
One of

  • LatLong
  • Address
  • State
  • City
  • County
  • Neighborhood
  • PostalCode
  • Country
  • ZipPlus4
  • CityPostalCode
3usageString

Copy
usage: "Business"
Only valid for US address LocationType. This indicates the US Postal Service opinion about whether this address is primarily a “Business” or “Residential”.

4legal_entities_atArray

Legal entities (people or businesses) that share this address. Please refer to the Person or Business Id data structure for more details here.

5standard_address_line1String

Copy
standard_address_line1: "9702 NE 120th Pl"
Canonicalized and validated address_line1. Contains both primary and the optional secondary address data. Example: “1301 5th Ave Ste 1600”.

6standard_address_line2String

Copy
standard_address_line2: "Apt 5"
Secondary address data. E.g.: “Ste 1600”

7cityString

Copy
city: "Kirkland"
Canonicalized city name. Example: “Olympia”.

8postal_codeString

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

9zip4String

Copy
postal_code: "4206"
4-digit US zipcode extension. Example: “1020”.

10state_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 State or “BC” for British Columbia.

11country_codeString

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

12is_deliverableBoolean

Copy
is_deliverable: true
Only valid for a LocationType “address”. Indicates whether the Postal Service can deliver mail to this address.

13is_receiving_mailBoolean

Copy
is_receiving_mail: true
Only valid for US address LocationType. If true, then this indicates that the US Postal Service believes that mail delivered to that address will be collected. If false, then the not_receiving_mail_reason field will be set

14not_receiving_mail_reasonString

Copy
not_receiving_mail_reason: null
The reason why the is_receiving_mail field value is false. One of:

  • Vacant
  • New Construction
  • Rural
15delivery_pointString

Copy
delivery_point: "SingleUnit"
Only valid for US address LocationType. Indicates to the US Postal Service whether deliver of mail requires special handling. One of:

  • CommercialMailDrop
  • POBoxThrowback
  • POBox
  • MultiUnit
  • SingleUnit
16address_typeString

Copy
address_type:"Street"
Only valid for US address LocationType. In conjunction with the delivery_point and box_type fields, this provides additional information about the receiving mail address. One of:

  • Firm
  • GeneralDelivery
  • Highrise
  • POBox
  • RuralRoute
  • Street
17lat_longObject

Latitude, longitude and accuracy of this location in a data structure. For locations larger than addresses, this is the centroid of the location area.

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
  • City
  • State
  • Country

Example

Request

Copy
https://proapi.whitepages.com/2.2/location.json?city=ashland&postal_code=59004&state=mt&street_line_1=3023+Hansberry+Ave&api_key=KEYVAL

Response

Copy
{
"results":[
{
"id":{
"key":"Location.2e429fc8-ca9e-4c8c-a79b-c702de43bc2a.Durable",
"type":"Location"
},
"type":"Address",
"valid_for":null,
"legal_entities_at":[
{
"id":{
"key":"Business.a4f1a841-8ba5-4786-a754-68ee3949383e.Durable",
"type":"Business"
},
"name":"Cafe Juanita",
"locations":null,
"phones":[
{
"id":{
"key":"Phone.e9a36fef-a2e0-4b08-cfe3-bc7128b7fb9e.Durable",
"type":"Phone"
},
"line_type":null,
"belongs_to":null,
"associated_locations":null,
"is_valid":true,
"phone_number":"4258231505",
"country_calling_code":"1",
"extension":null,
"carrier":null,
"do_not_call":false,
"reputation":null,
"is_prepaid":null,
"is_connected":null,
"valid_for":null,
"contact_type":"Business",
"contact_creation_date":1450743916
}
],
"urls":null
},
{
"id":{
"key":"Business.73fd41bf-0883-4934-bb1f-a25a69f35174.Durable",
"type":"Business"
},
"name":"Abel Locksmith",
"locations":null,
"phones":[
{
"id":{
"key":"Phone.ccdb6fef-a2e0-4b08-cfe3-bc7128b7fb65.Durable",
"type":"Phone"
},
"line_type":null,
"belongs_to":null,
"associated_locations":null,
"is_valid":true,
"phone_number":"4256360045",
"country_calling_code":"1",
"extension":null,
"carrier":null,
"do_not_call":false,
"reputation":null,
"is_prepaid":null,
"is_connected":null,
"valid_for":null,
"contact_type":"Business",
"contact_creation_date":1450658366
}
],
"urls":null
}
],
"city":"Kirkland",
"postal_code":"98034",
"zip4":"4206",
"state_code":"WA",
"country_code":"US",
"is_receiving_mail":true,
"not_receiving_mail_reason":null,
"usage":"Business",
"delivery_point":"SingleUnit",
"address_type":"Street",
"lat_long":{
"latitude":47.707649,
"longitude":-122.212463,
"accuracy":"RoofTop"
},
"is_deliverable":true,
"standard_address_line1":"9702 NE 120th Pl",
"standard_address_line2":""
}
],
"messages":[
]
}