Let's Program This
Seeing it all work in your browser is great, but you're not going to manually open thousands of URLs – this is not what you started programming for!
Luckily, it's very easy to use the Pipl API in your existing codebase, or as a new script. If you use any one of the 5 supported programming languages – Python, Java, C#, PHP or Ruby, you’re in luck. Just head over to https://pipl.com/dev/guide/code_libraries and grab the client library for your chosen programming language.
If you use another technology, it's still fairly trivial to code up a basic wrapper – the API has a single endpoint and uses JSON responses.
Step 1: Install
The first thing you need is to get a hold of the applicable client library. Each library is available in the major dependency management solution of its respective language. For python this means:
pip install piplapis-python
The library is now available for import in python files.
Step 2: Import
To start using the python client library, add the import statement:
Let's go over the basic structure of the piplapis module:
- search – this is where the actual search logic resides.
- SearchAPIRequest: the request class. To run a search, you create an instance with the search parameters, and execute it via the send() method.
- SeachAPIResponse: the return type of SearchAPIRequest.send(). This is a response object, which contains the response person, as well as some data about the execution of the search.
- data – the python datamodel of Pipl objects is stored here. Individual data points such as Address, Phone, Name and so on are located in data.fields, while container objects such as Person and Source are located in data.containers.
Step 3 – Get it running
Let's say your application has a Subscriber model, which holds data about a newsletter subscriber. Here is the model definition as a simple class:
class Subscriber(object): def __init__(self, *args, **kwargs): self.first_name = None self.last_name = None self.email = None self.phone = None self.age = None self.job_title = None self.photo = None self.language_pref = None
As of now, the only property that has a value, is Subscriber.email. Let's see what we can do about that.
First of all, we'll make sure new users have more data. We're going to add this code to the newsletter signup handler:
search_request = SearchAPIRequest(email=subscriber.email, api_key="YOUR_API_KEY") search_response = search_request.send() if search_response.image is not None: subscriber.phone = search_response.phone.display if search_response.job is not None: subscriber.job_title = search_response.job.title if search_response.language is not None: subscriber.language_pref = search_response.language.display if search_response.image is not None: subscriber_photo = search_response.image.get_thumbnail_url(width=200, height=200) if search_response.name is not None: subscriber.first_name = search_response.name.first subscriber.last_name = search_response.name.last if search_response.dob is not None: subscriber.phone = search_response.dob.age
Some of you may have noticed that I don't access the SearchAPIResponse.person attribute to access the data. Instead, I use the handy shortcut properties available within the SearchAPIResponse class, which returns the best phone, the best name, and so forth. For more complex use cases, you'd access the person object directly, and use the list of phones, the list of names, and so on.
Now all new subscribers will automatically be saved with some useful information and you'll be able to start doing cool stuff, such as mailing some newsletters only to a specific age group.
Of course, you'll probably want to implement a batch script to update all your existing customers. This is fairly trivial to implement using a simple loop, but depending on your dataset size, you may want to execute it using multiple threads. In this case, be sure to note the quota-per-second limits. Details about these are available in this FAQ page - https://pipl.com/dev/guide/faq.
Step 4 – Multiple matches
We have glossed over one scenario. When you make a Pipl API call, the Response object will include either a top-level Person object, or an array of Person objects under the possible_persons property.
The possible persons list is returned whenever the Pipl identity resolution could not resolve the data to a single match. In this case, there may be multiple matches, all pointing to different people. They will be ordered by a match score (available in the Power package and up), so sometimes taking the first possible person will be sufficient.
If there's no high-ranking possible person, or you'd rather take the fail-safe method, have a look at the @search_id of the possible person. The search ID is a property of the person object, and it allows you to run follow-up searches, in order to get more data about a specific possible person. For a full explanation of the search pointer and how to use it, visit this tutorial: https://pipl.com/corp/possible-persons/.
Getting More Information
So there you have it. Your dataset now includes the name, phone, age and profile picture of your newsletter subscribers.
I hope you found this tutorial useful. For more information on using the Pipl API, the following resources are great for starting out:
- Introduction - https://pipl.com/dev/guide/introduction
- How to do common stuff in different programming languages - https://pipl.com/dev/guide/code_snippets
- A high-level explanation of the available data types: https://pipl.com/dev/guide/data_types
- The full API reference, keep on hand while developing: https://pipl.com/dev/reference/