How to get Social and Professional Info From Email Addresses with Pipl

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:

import piplapis

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

NOTE:
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:

Be sure to read the next Email article: How to Build Your First iOS App That Uses GMail’s API

 

Comments (4)

Rohit_M

Thanks for the article on the pipl api

for it to work I had to add the following otherwise getting error on SearchAPIRequest

import piplapis

from piplapis import search

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

subscriber=Subscriber()

subscriber.email = 'rdm750@gmail.com'

search_request = search.SearchAPIRequest(email=subscriber.email, api_key="sample_key")

Rohit_M

Thanks.  For it to work I had to import search from the pipl api

'''

>>> help(piplapis)

 

Help on package piplapis:

 

NAME

    piplapis

 

FILE

    /Library/Python/2.7/site-packages/piplapis/__init__.py

 

PACKAGE CONTENTS

    data (package)

    error

    search

    thumbnail

 

DATA

    __version__ = '5.1.0'

 

VERSION

    5.1.0

 

(END)

'''

 

import piplapis

from piplapis import search

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

subscriber=Subscriber()

subscriber.email = 'rdm750@gmail.com'

search_request = search.SearchAPIRequest(email=subscriber.email, api_key="sample_key")