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 anydirectional 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
Return to the main documentation page
Copyright © 2008 WhitePages.com. All rights reserved.
Comments