WhitePages Pro API Test Account Documentation

The WhitePages Pro API is a RESTful interface in which simple HTML GET requests are used to access the API. The WhitePages.com API will provide XML responses by default. Optionally, the response format can be specified as JSON if desired. Other formats may be supported in the future. This protocol is simple to use and accessible from any common web programming language on any machine with internet access.

The following API functions are available with a WhitePages Pro API Test Account:

  • find_person - Retrieves contact information about a person, such as a telephone number and address
  • reverse_phone - Retrieves contact information about a telephone number
  • reverse_address - Retrieves contact information about the people at an address
  • find_business - Retrieves contact information about a business

Registration Required

You must register for a Pro API Test Account and be issued an API key. The key will be attached to each query you send to the API.  Limit one API key per account.

Register for an Account  |  Apply for and API Key

Request Format

Each search request consists of the following parts:

  1. The base URL, http://api.whitepages.com/
  2. The search type, either find_person, reverse_phone, or reverse_address
  3. The API version, currently 1.0
  4. The search parameters, which is a semicolon separated list of parameter=value entries
  5. The API key parameter with your API key value, which is the unique identifier you received when you registered.

For example, to search for the person "Mike Smith" in Seattle, the request would look like:

http://api.whitepages.com/find_person/1.0/?firstname=mike;lastname=smith;zip=98101;api_key=API_KEYVAL

where API_KEYVAL is your API key value.

About the Response

There are four categories of search responses:

  • The results response - response with one or more search results records.
  • The no results response - response when no search result records were found.
  • The request for clarification response - response when a search was ambiguous and needs clarification, most commonly when a location such as a city is incompletely described in the search request. A list of possible alternatives is provided in this response.
  • The error response - response with an error message, such as a required parameter was missing.

Each of these responses share a common Data Dictionary which describes the elements that may be returned by the WPAPI.

Links in the Response

A successful search response will also include some links which can be used for more detailed information. The specific links returned will depend on the search type and the results. Each link returned will include a description, a text field which describes the link and is suitable for display, and the URL of the link. These links will be chosen from among:

  • View Map: displays a map of the address.
  • Driving Directions: displays a map of the address and provides a way to get driving directions to the address.
  • View Listing Details: displays information about the person, such as Web results, public records, and professional profiles.
  • View All Results: displays additional listings if more listing were found beyond the API search limits.
  • View Work Listings: displays only work listings, but may be convenient if some work and some residential listings were found.
  • Find Neighbors: displays information about the address, such as Web results, neighbors, and nearby businesses.
  • View Search Suggestions: displays some alternate suggestions for searches which returned no results.
  • WhitePages.com: links to the home page of WhitePages.com

Response Format

The XML response returned by the API conforms to this XSD.

Frequently Asked Questions

Answers to some frequently asked questions about a WhitePages Pro API Test Account may be found in the  FAQ.

Copyright © 2011 WhitePages.com. All rights reserved.



version 3 as of 2 years ago by erogers

0 Comments

Please sign in to post a comment.