Picklist Response

If the search criteria are too ambiguous to produce a clear result, 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, given the following search query, which is for someone named "smith" in the city "portland":

http://api.whitepages.com/find_person/1.0/?lastname=smith;city=portland;api_key=API_KEY

The results response (the elements are described below) seeks clarification since Portland is found in several states. The actual response should look like the following:

<wp:wp>
    <wp:result wp:type="error" wp:message="One or more input parameters are invalid" wp:code="Refine Input"/>
    <wp:errormessages>
        <wp:message>Refine Input: multiple cities found</wp:message>
    </wp:errormessages>
    <wp:meta>
        <wp:linkexpiration>2008-01-01</wp:linkexpiration>
        <wp:recordrange wp:lastrecord="0" wp:firstrecord="0" wp:totalavailable="10"/>
        <wp:apiversion>1.0</wp:apiversion>
        <wp:searchlinks>
            <wp:link wp:linktext="Whitepages.com" wp:type="homepage">http://www.whitepages.com</wp:link>
            <wp:link wp:linktext="Link to this api call" wp:type="self">
                URL_TO_THIS_API_CALL
            </wp:link>
        </wp:searchlinks>
    </wp:meta>
    <wp:options>
        <wp:cityoption wp:country="US" wp:city="PORTLAND" wp:state="AR">
            <wp:refinesearchurl>
                URL_TO_THIS_API_CALL;state=AR
            </wp:refinesearchurl>
        </wp:cityoption>
        <wp:cityoption wp:country="US" wp:city="PORTLAND" wp:state="CO">
            <wp:refinesearchurl>
                URL_TO_THIS_API_CALL;state=CO
            </wp:refinesearchurl>
        </wp:cityoption>
        <wp:cityoption wp:country="US" wp:city="PORTLAND" wp:state="CT">
            <wp:refinesearchurl>
                URL_TO_THIS_API_CALL;state=CT
            </wp:refinesearchurl>
        </wp:cityoption>
        <wp:cityoption wp:country="US" wp:city="PORTLAND" wp:state="IA">
            <wp:refinesearchurl>
                URL_TO_THIS_API_CALL;state=IA
            </wp:refinesearchurl>
        </wp:cityoption>
        <wp:cityoption wp:country="US" wp:city="PORTLAND" wp:state="IL">
            <wp:refinesearchurl>
                URL_TO_THIS_API_CALL;state=IL
            </wp:refinesearchurl>
        </wp:cityoption>
        <wp:cityoption wp:country="US" wp:city="PORTLAND" wp:state="IN">
            <wp:refinesearchurl>
                URL_TO_THIS_API_CALL;state=IN
            </wp:refinesearchurl>
        </wp:cityoption>
        <wp:cityoption wp:country="US" wp:city="PORTLAND" wp:state="KY">
            <wp:refinesearchurl>
                URL_TO_THIS_API_CALL;state=KY
            </wp:refinesearchurl>
        </wp:cityoption>
        <wp:cityoption wp:country="US" wp:city="PORTLAND" wp:state="ME">
            <wp:refinesearchurl>
                URL_TO_THIS_API_CALL;state=ME
            </wp:refinesearchurl>
        </wp:cityoption>
        <wp:cityoption wp:country="US" wp:city="PORTLAND" wp:state="MI">
            <wp:refinesearchurl>
                URL_TO_THIS_API_CALL;state=MI
            </wp:refinesearchurl>
        </wp:cityoption>
        <wp:cityoption wp:country="US" wp:city="PORTLAND" wp:state="MO">
            <wp:refinesearchurl>
                URL_TO_THIS_API_CALL;state=MO
            </wp:refinesearchurl>
        </wp:cityoption>
    </wp:options>
</wp:wp>

where:
URL_TO_THIS_API_CALL is the same URL as the original query

Data Elements

The data elements that may be found in a clarification response are described in the following table.

Attribute	Description	Notes
result	The result status of the search request
type	The type of result	error means the request contained invalid or ambiguous data success means the request returned 0 or more records This attribute should be error in a clarification response.
message	A textual description of the error
code	An error code	Refine Input means that the input data was ambiguous This attribute should be Refine Input in a clarification response.
message	Information pinpointing the cause of the error	Typically Refine Input:multiple cities found
linkexpiration	The date after which the links are no longer guaranteed to be valid	WhitePages.com does not guarantee any specific duration
lastrecord	The index of the last record in the list of records	This attribute should be 0 for a clarification response
firstrecord	The index of the first record in the list of records	This attribute should be 0 for a clarification response
totalavailable	The total number of alternates available to pick from	This attribute should be 2 or more for a clarification response
apiversion	The version of the API	This is 1.0 for this release
link	A link to additional information related to the search
linktext	A textual description suitable for display
linktype	The type of link
country	The country for a possible match	US for United States
city	The city for a possible match
state	The state for a possible match
options	A container for possible find_business category options
categoryoption	An individual option for a business category returned as part of a find_business category picklist.
refinesearchurl	URL link to a possible match

Picklist Response

Data Elements

0 Comments

Docs Navigation