find_person Search

Finds contact information for a person, based on name and location.

Syntax

http://api.whitepages.com/find_person/1.0/?parameter_list;api_key=API_KEYVAL

where parameter_list signifies one or more parameter=value entries separated by semicolons and API_KEYVAL is the API key value you received when you registered.

Parameters

Parameters can appear in any order. Parameter names are case-sensitive; parameter values case-insensitive. For example "lastname=smith" matches "Smith", but "Lastname=smith" is not a valid parameter assignment, since the parameter name is (all lower case) lastname and not (capitalized) Lastname.

Parameter	Required?	Notes	Example
firstname	no		firstname=robert
lastname	yes	see Note about required parameter	lastname=johnson
name	yes	see Note about required parameter	name="bill%20johnson"
house	no	The `house` parameter is the house number	house=400
street	no	the `street` parameter is the street name, including any directional prefix or suffix	street=maple%20st
city	no		city=seattle
state	no	USPS two-character abbreviation	state=wa
zip	no	will accept 5 digit ZIP Code or 9 digit ZIP+4	zip=98101
areacode	no		areacode=206
metro	no	Whether to expand the search to the metro area. The default value is 0 (false) which means searches are not expanded to metro area by default.	metro=1

Remarks

Note that only one of the parameters lastname or name is required. However, we recommend providing as much information as you have as that will give better results and faster response.

The name parameter is an optional way to specify the name of the person to be searched. For applications which use a single field name, this parameter can be passed directly to the WhitePages.com API. For applications which use separate firstname and lastname fields, these can be passed directly to the WhitePages.com API in their respective fields.

Note that the usual address line spans two parameters. The house number is separated from the street name. For a typical address such as 2468 East Main St, this would make the house parameter 2468 and the street parameter "East Main St". Of course, spaces in the street name should be encoded as %20 for passing over HTTP, so the street parameter as passed to the API would be "East%20Main%20St"

The firstname and lastname parameters support both an exact name match as well as a "begins with" match. To search for "Bernie" or "Bert" set the firstname parameter to "Ber*". The asterisk ("*") is called a "wild card" character. No other parameters support this character and it can only be used to match the end of a first name or the end of a last name.

Searches for common nicknames, such as searching for "Doug" or "Douglas" as a first name, are automatically done without requiring the wildcard in the firstname field. If multiple matches are found the listings will be ordered so that more exact matches to the search parameters will be presented first with nicknames or other wildcard results lower in the results set.

The metro parameter is a Boolean value where 1 signifies true or 0 signifies false. It specifies whether to expand the search to include the metropolitan area around the specified city parameter value.

Limitations

A find_person search will return at most 20 listings using the WPAPI. Additional listings may be available by following one of the URLs returned as links with a successful search.

Example

The following example specifies a search for Mike Smith on Main street in Seattle, Washington.

http://api.whitepages.com/find_person/1.0/?firstname=Mike;lastname=Smith;street=Main;city=seattle;state=wa;api_key=API_KEYVAL