Article

Smart Updates to Pro APIs

At Whitepages Pro, we’re always looking to make our products even better. We released Developer Portal last fall, opening up our APIs for developers to try out and leverage identity data into their applications. It has been single best source of customer feedback for us. We continue to be amazed at the different people using our APIs and providing us with feedback that has been absolutely crucial in our development efforts. Everyone from developers to product managers, CIOs and even CEOs sign up for the API Key and try our Graph Explorer to understand the data we provide and how they can integrate it into their solutions. Thanks to all of your feedback, I am excited to announce new API updates, which take into account each of these personas and their different needs.

Previously, Pro APIs followed a dictionary-based route to its responses. So for instance, if you performed a Reverse Phone query, your response and the data associated with it would look like this:

Image_1

The big benefit we drew from this approach is that it avoids duplication. So for example, if multiple people associated with a phone number are living at the same address, then we do not list the same address again for each person. All of the people structures reference the same location. See the red box in the image below for an illustration:

Image_2

 

Here we reference the Person who owns the phone number via the structure “id: {}”. The image above also shows that the Person result is represented in a separate id: {}” within the results.

However, feedback we got from customers, especially Product Managers, CIOs and CEOs who initially are just interested in a visual walk through of the API response for validation of the data, is that this format can be hard to follow. So to simplify the process, we are excited to announce the release of tree-based API responses. Now for a Reverse Phone query, the response looks like this:

Image_3

 

As you can see the belongs to Person or the Location is all nested. It is not a reference from one Id structure to another. While there will be some duplication, for a lot of our customers this response greatly simplifies walking through the response and parsing the values of interest.

Another huge advantage is that now you can use XPath style JSONPaths to traverse through the tree and extract the values of interest. For example, a regular expression to find the name associated with the phone now looks like this:

root.results[0].belongs_to[0].best_name

The question I am sure you have is, “Does this break the existing customers?” The answer is no it does not. The tree-based response is available as a minor version increment, 2.1, to Pro APIs. See it here:

http://proapi.whitepages.com/2.1/phone.json?phone_number=2069735100&api_key=KEYVAL

Existing customers can continue to work with 2.0. They need not move to 2.1 if they have already coded to 2.0 APIs. For new customers, you have the choice to use the tree-based response or continue with dictionary responses. Dictionary-based responses are available in 2.1 as well as an additional parameter:

http://proapi.whitepages.com/2.1/phone.json?phone_number=2069735100&api_key=KEYVAL&result_format=dictionary

Note that there is no data discrepancy between 2.0 and 2.1 APIs. Both return the same data payload.

Questions, comments, concerns? – Let me know at kshah [at] whitepages [dot] com!

Thanks for reading! You might be interested in these posts, too: