Results Response

If the search produces results, the search returns a response containing one or more records. The default XML format response is described below. See the section on optional JSON output for an illustration of how this might differ if optional JSON output format was requested.

For example, suppose the following search query, which is for someone named Mike Smith who lives on Main Street in Seattle, produces a result:

http://api.whitepages.com/find_person/1.0/?lastname=smith;firstname=mike;street=main%20st;city=seattle;api_key=API_KEY

The results response (the elements are described below) should look something like the following:

  <?xml version="1.0" encoding="UTF-8" ?> 
  <wp:wp xmlns:wp="http://api.whitepages.com/schema/">
  <wp:result wp:type="success" wp:message="" wp:code="Found Data" /> 
  <wp:meta>
  <wp:linkexpiration>2008-03-18</wp:linkexpiration> 
  <wp:recordrange wp:lastrecord="1" wp:firstrecord="1" wp:totalavailable="1" /> 
  <wp:apiversion>1.0</wp:apiversion> 
  <wp:searchlinks>
  <wp:link wp:linktext="Whitepages.com" wp:type="homepage">http://www.whitepages.com/16176/</wp:link> 
  <wp:link wp:linktext="Link to this api call" wp:type="self">http://api.whitepages.com/find_person/1.0?firstname=mike;lastname=smith;street=main;city=seattle;state=wa;api_key=API_KEYVAL</wp:link> 
  </wp:searchlinks>
  </wp:meta>
  <wp:listings>
  <wp:listing>
  <wp:people>
  <wp:person wp:rank="primary">
  <wp:firstname>Mike</wp:firstname> 
  <wp:lastname>Smith</wp:lastname> 
  </wp:person>
  </wp:people>
  <wp:phonenumbers>
  <wp:phone wp:type="home" wp:rank="primary">
  <wp:fullphone>(206) 973-0000</wp:fullphone> 
  <wp:areacode>206</wp:areacode> 
  <wp:exchange>973</wp:exchange> 
  <wp:linenumber>0000</wp:linenumber> 
  </wp:phone>
  </wp:phonenumbers>
  <wp:address wp:deliverable="true">
  <wp:fullstreet>2468 Main St</wp:fullstreet> 
  <wp:house>2468</wp:house> 
  <wp:street>Main St</wp:street> 
  <wp:streettype>St</wp:streettype> 
  <wp:city>Seattle</wp:city> 
  <wp:state>WA</wp:state> 
  <wp:zip>98101</wp:zip> 
  <wp:country>US</wp:country> 
  </wp:address>
  <wp:geodata>
  <wp:geoprecision>1</wp:geoprecision> 
  <wp:latitude>41.876840</wp:latitude> 
  <wp:longitude>-87.638160</wp:longitude> 
  </wp:geodata>
  <wp:listingmeta>
  <wp:moreinfolinks>
  <wp:link wp:linktext="Find Neighbors" wp:type="findneighbors">http://www.whitepages.com/16176/track/10214/search/FindNeighbors?addr_research=1&tmpl=search_research_neighbors&search_id=51131403267465603149&rarl=&element_id=1</wp:link> 
  <wp:link wp:linktext="View Map" wp:type="viewmap">http://www.whitepages.com/16176/track/10213/map_provider?full_address=2468+Main+St&city=Seattle&state=WA&zip=98101&country=US&lat=41.876840&long=-87.638160&name=Smith&firstname=Mike&show_form=false</wp:link> 
  <wp:link wp:linktext="Driving Directions" wp:type="drivingdirections">http://www.whitepages.com/16176/track/10216/map_provider?=&show_form=true&full_address=2468+Main+St&city=Seattle&state=WA&zip=98101&country=US&lat=41.876840&long=-87.638160&name=Smith&firstname=Mike</wp:link> 
  <wp:link wp:linktext="View Listing Detail" wp:type="viewdetails">http://www.whitepages.com/16176/track/10215/search/Replay?search_id=51131403267465603149&lower=1&more_info=1</wp:link> 
  </wp:moreinfolinks>
  </wp:listingmeta>
  </wp:listing>
  </wp:listings>
  </wp:wp>

Links Returned

In the results response, there will be several links returned which can provide additional information. These links are valid through the wp:linkexpiration date, typically several days.
wp:linktext="Link to this api call" is the same URL as the original query
wp:linktext="Find Neighbors" is the URL to where additional information can be found on the neighbors
wp:linktext="View Map" is the URL to where a map of the address can be found
wp:linktext="Driving Directions" is the URL to where driving directions to the address can be found
wp:linktext="View Listing Detail" is the URL to where additional information on the person can be found

Limitations and Record Counts

Typically, the number of results returned is limited based on search results and based on the type of query which was requested. A find_person query will return at most 20 records. A reverse_phone query will return at most 5 records. A reverse_address query will return at most 10 records.

If there are more results than can be provided within the limits above, there will also be a wp:link with wp:linktext="View All Results" provided. The URL provided to "View All Results" can be used to see the additional listings on the www.WhitePages.com site, up to the typical site limit of 300 results.

Data Dictionary

The individual elements of a results response are described in the Data Dictionary and the format of a valid response is described in the XML Schema Definition (XSD).

Return to the main documentation page

Copyright © 2011 WhitePages.com. All rights reserved.