Code Snippets and Example Programs

The following snippets and examples are meant to highlight some commonly used capabilities of the API. For a complete understanding of the API's features, please refer to the libraries' source code (available on github).

Example Scripts

Example scripts using the Pipl API can be found at the Search API Examples github page

Code Snippets

Below are a few snippets for the basic things that you can do with the API Code Libraries.

Creating a request

Option 1 - This is a fast, direct method for simple requests with few parameters:

Python

from piplapis.search import SearchAPIRequest
request = SearchAPIRequest(email=u'clark.kent@example.com', api_key='YOURKEY')

Ruby

require 'pipl'
response = Pipl::client.search email: 'clark.kent@example.com', api_key: 'YOURKEY'

Java

import com.pipl.api.search.SearchAPIRequest;
import com.pipl.api.search.SearchAPIResponse;
import com.pipl.api.search.SearchConfiguration;

SearchConfiguration configuration = new SearchConfiguration();
configuration.setProtocol("https");
configuration.apiKey = 'YOURKEY'
  
SearchAPIRequest request = new
SearchAPIRequest.Builder().email("clark.kent@example.com").firstName("Clark").lastName("Kent").configuration(configuration).build();

PHP

<?php

require_once './piplapis/search.php';

$configuration = new PiplApi_SearchRequestConfiguration();
$configuration->use_https = true;
$configuration->api_key = 'YOURKEY';
  
$request = new PiplApi_SearchAPIRequest(array('email' => 'clark.kent@example.com',
'first_name' => 'Clark',
'last_name' => 'Kent'), $configuration);

?>

C#

using Pipl.APIs.Search;
SearchConfiguration searchConfiguration = new SearchConfiguration(apiKey: "YOURKEY",url: "api.pipl.com/search/", useHttps: true);
SearchAPIRequest request = new SearchAPIRequest(email: "clark.kent@example.com",
firstName: "Clark",
lastName: "Kent", requestConfiguration: searchConfiguration);

Option 2 - Using the data-model. This method is useful for more complex queries, such as when you need to send multiple values of the same field type:

Python

from piplapis.data import Person, Name, Address, Job

fields = [Name(first=u'Clark', last=u'Kent'),
          Address(country=u'US', state=u'KS', city=u'Smallville'),
          Address(country=u'US', state=u'KS', city=u'Metropolis'),
          Job(title=u'Field Reporter')]
request = SearchAPIRequest(person=Person(fields=fields), api_key='YOURKEY')

Ruby

person = Pipl::Person.new
person.add_field Pipl::Name.new(first: 'Clark', last: 'Kent')
person.add_field Pipl::Address.new(country: 'US', state: 'KS', city: 'Smallville')
person.add_field Pipl::Address.new(country: 'US', state: 'KS', city: 'Metropolis')
person.add_field Pipl::Job.new(title: 'Field Reporter')

response = Pipl::client.search person: person, api_key: 'YOURKEY'

Java

import java.util.ArrayList;
import java.util.List;
import com.pipl.api.search.SearchAPIRequest;
import com.pipl.api.data.containers.Person;
import com.pipl.api.data.fields.*;

import com.pipl.api.search.SearchConfiguration;

SearchConfiguration configuration = new SearchConfiguration();
configuration.setProtocol("https");
configuration.apiKey = 'YOURKEY';

List<Field> fields = new ArrayList<Field>();
fields.add(new Name.Builder().first("Clark").last("Kent").build());
fields.add(new Address.Builder().country("US").state("KS").city("Smallville").build());
fields.add(new Address.Builder().country("US").state("KS").city("Metropolis").build());
fields.add(new Job.Builder().title("Field Reporter").build());
Person person = new Person(fields);
// Or the short version:
// Person person = new Person(new Name(null, "Clark", null, "Kent", null), new Address("US", "KS", "Smallville", null, null, null, null, null), new Address("US", "KS", "Metropolis", null, null, null, null, null), new Job("Field Reporter", null, null));
SearchAPIRequest request = new SearchAPIRequest(person, configuration);

PHP

<?php
$configuration = new PiplApi_SearchRequestConfiguration();
$configuration->use_https = true;
$configuration->api_key = 'YOURKEY';

$fields = array(new PiplApi_Address(array("country" => "US",
                                          "state" => "KS", "city" => "Metropolis")),
                new PiplApi_Address(array("country" => "US",
                                          "state" => "KS", "city" => "Smallville")),
                new PiplApi_Name(array("first" => "Clark",
                                       "middle" => "Joseph", "last" => "Kent")),
                new PiplApi_Job(array("title" => "Field Reporter")),
);
$person = new PiplApi_Person($fields);
$request = new PiplApi_SearchAPIRequest(array('person' => $person), configuration);

return $request;

C#

using Pipl.APIs.Search;
SearchConfiguration searchConfiguration = new SearchConfiguration(apiKey: "YOURKEY",url: "api.pipl.com/search/", useHttps: true);

List<Field> fields = new List<Field>()
{
    new Name(first: "Clark",last: "Kent"),
    new Address(country: "US", state: "KS", city: "Smallville"),
    new Address(country: "US", state: "KS", city: "Metropolis"),
    new Job(title: "Field Reporter")
};

var person = new Person(fields);

SearchAPIRequest request = new SearchAPIRequest(person: person, requestConfiguration: searchConfiguration);

Sending a request

Option 1 – Synchronously

Python

from piplapis.search import SearchAPIError
try:
    response = request.send()
except SearchAPIError as e:
    print(e.http_status_code, e)

Ruby

begin
  response = Pipl::client.search email: 'clark.kent@example.com'
rescue Pipl::Client::APIError => e
  puts e.status_code, e.message
end

Java

import java.io.IOException;
import com.pipl.api.search.SearchAPIError;
import com.pipl.api.search.SearchAPIResponse;

try {
    SearchAPIResponse response = request.send();
} catch (SearchAPIError | IOException e) {
    e.printStackTrace();
}

PHP

<?php
try {
    $response = $request->send();
} catch (PiplApi_SearchAPIError $e) {
    print $e->getMessage();
}

C#

try
{
    var response = await _request.SendAsync();
}
catch (SearchAPIError e)
{
    Console.Out.WriteLine(e.ToString());
}
catch (IOException e)
{
    Console.Out.WriteLine(e.ToString());
}

Option 2 – Async: Send the query with a non-blocking call

Python

def my_callback(response=None, error=None):
    print response or error

request.send_async(my_callback)
do_other_things()

Ruby

thread = Pipl::client.search email: 'clark.kent@example.com', async: true do |resp|
  puts resp[:response] or resp[:error]
end
do_other_things()

Java

import java.util.concurrent.ExecutionException;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;
import java.util.concurrent.Future;

ExecutorService threadPool = Executors.newSingleThreadExecutor();
// Other alternatives contain more advanced thread pools and FutureTask.
Future<SearchAPIResponse> future = threadPool.submit(request.sendAsync(false));
doOtherThings();
try {
    SearchAPIResponse response = future.get();
} catch (InterruptedException | ExecutionException e) {
    e.printStackTrace();
}

PHP

# Not available in PHP

C#

var task = _request.SendAsync();

_doOtherThings();

try
{
    var response = task.Result;
}
catch (TaskCanceledException e)
{
    Console.Out.WriteLine(e.ToString());
}

Working with a response

📘 A response can return either a Person , a list of Possible Persons , or no data.

When working with the response, first check for a person object. If it's null, check for the possible_persons array. If there are neither, there is no data in the response (the persons_count property will be 0 in this case).

The below syntax is available for all fields to quickly access frequently used data (the most recent name, last address, most prominent username, etc.). For example, when using the fast, direct option #1 method:

Python

>>> print(response.name)
u'Clark Joseph Kent'
>>> print(response.gender)
u'Male'
>>> print(response.address)
u'10-1 Hickory Lane, Smallville, Kansas'
>>> print(response.job)
u'Field Reporter at The Daily Planet (2000-2012)'

Ruby

puts response.name
# Output: 'Clark Joseph Kent'
puts response.gender
# Output: 'Male'
puts response.address
# Output: '10-1 Hickory Lane, Smallville, Kansas'
puts response.job
# Output: 'Field Reporter at The Daily Planet (2000-2012)'

Java

System.out.println(response.name());
// Output: "Clark Joseph Kent"
System.out.println(response.gender());
// Output: "Male"
System.out.println(response.address());
// Output: "10-1 Hickory Lane, Smallville, Kansas"
System.out.println(response.job());
// Output: "Field Reporter at The Daily Planet (2000-2012)"

PHP

<?php
print $response->person->addresses[0]; // 10-1 Hickory Lane, Smallville, Kansas

C#

Console.Out.WriteLine(_response.Name);
// Output: "Clark Joseph Kent"
Console.Out.WriteLine(_response.Gender);
// Output: "Male"
Console.Out.WriteLine(_response.Address);
// Output: "10-1 Hickory Lane, Smallville, Kansas"
Console.Out.WriteLine(_response.Job);
// Output: "Field Reporter at The Daily Planet (2000-2012)"

Access the person object that came with the response:

Python

>>> response.person
<piplapis.data.containers.Person object at 0x02849E50>
>>> response.person.addresses
[Address(country=u'US', state=u'KS', city=u"Metropolis", street=u"Broadway", house=u"1000", apartment=u"355"), Address(country=u'US', state=u'KS', city=u"Smallville", street=u"Hickory Lane", house=u"10", apartment=u"1")]

Ruby

puts response.person.addresses
# Output: '10-1 Hickory Lane, Smallville, Kansas'
# Output: '1000-355 Broadway, Metropolis, Kansas'

Java

System.out.println(response.getPerson().getAddresses().get(0));
// Output: "10-1 Hickory Lane, Smallville, Kansas"

PHP

<?php
print $response->person->addresses[0]; // 10-1 Hickory Lane, Smallville, Kansas

C#

Console.Out.WriteLine(_response.Person.Addresses[0]);
// Output: "10-1 Hickory Lane, Smallville, Kansas"

Working with sources

Access the response data's list of sources. This is only available if you set the “show_sources” flag to “all” or “matching”:

Python

>>> len(response.sources)
2
>>> response.sources[0]
<piplapis.data.containers.Source object at 0x02849D22>
>>> response.sources[0].phones
[Phone(country_code=1, number=9785550145)]
>>> response.sources[0].origin_url
u'http://linkedin.com/clark.kent'

Ruby

response = Pipl::client.search email: 'clark.kent@example.com', show_sources: 'all'
puts response.sources[1].phones[0].display
# Output: '(978) 555-0145'
puts response.sources[1].origin_url
# Output: 'http://facebook.com/superman'

Java

System.out.println(response.getSources().size());
// Output: 2
System.out.println(response.getSources().get(1).getPhones().get(0).getDisplayInternational());
// Output: "+1 978-555-0145"
System.out.println(response. getSources().get(0).getOriginUrl());
// Output: "http://linkedin.com/clark.kent"

PHP

<?php
print count($response->sources); // 2
print $response->sources[1]->phones[0]->display_international; // http://linkedin.com/clark.kent
print $response->sources[1]->domain; // linkedin.com

C#

Console.Out.WriteLine(_response.Sources.Count);
// Output: 2
Console.Out.WriteLine(_response.Sources[1].Phones[0].DisplayInternational);
// Output: "+1 978-555-0145"
Console.Out.WriteLine(_response.Sources[0].OriginUrl);
// Output: "http://linkedin.com/clark.kent"

Group sources. Sources can be grouped by domain, category, match and more:

Python

>>> type(response.group_sources_by_domain())
<type 'dict'>
>>> response.group_sources_by_domain().get(u'linkedin.com')
[<piplapis.data.containers.Source object at 0x02849D24>, <piplapis.data.containers.Source object at 0x02849D28>]

Ruby

response = Pipl::client.search email: 'clark.kent@example.com', show_sources: 'all'
puts response.group_sources_by_domain['linkedin.com'].size
# Output: 1

Java

System.out.println(response.groupSourcesByDomain().get("linkedin.com").size());
// Output: 1

PHP

<?php
print gettype($response->group_sources_by_domain()['linkedin.com']); // array
print get_class($response->group_sources_by_domain()['linkedin.com'][0]); // PiplApi_Source

C#

Console.Out.WriteLine(_response.GroupSourcesByDomain()["linkedin.com"].Count());
// Output: 1

Useful utilities

There are useful utilities implemented for the field objects. Here are some examples:

Python

>>> address = response.address
>>> address.state
u'KS'
>>> address.state_full
u'Kansas'

>>> email = response.email
>>> email.username
u'clark.kent'

Ruby

address = response.address
puts address.state
# Output: 'KS'
puts address.state_full
# Output: 'Kansas'

email = response.email
puts email.username
# Output: 'clark.kent'

Java

Address address = new Address.Builder().country("US").state("KS").build();
System.out.println(address.getState());
// Output: "KS"
System.out.println(address.stateFull());
// Output: "Kansas"

Email email = new Email.Builder().address("clark.kent@example.com").build();
System.out.println(email.username());
// Output: "clark.kent"

PHP

<?php
print $response->address()->state; // KS
print $response->address()->state_full(); // Kansas
print $response->email(); // clark.kent@example.com
print $response->email()->username; // clark.kent

C#

Address address = new Address(country: "US", state:"KS");
Console.Out.WriteLine(address.State);
// Output: "KS"
Console.Out.WriteLine(address.StateFull);
// Output: "Kansas"

Email email = new Email(address: "clark.kent@example.com");
Console.Out.WriteLine(email.Username);
// Output: "clark.kent"

Global Preferences

You also can set search preferences globally, and they will apply to all search requests. Examples shown in the snippet are the default preferences.

Setting global preferences is optional—you can choose query settings per request if you prefer.

Python

SearchAPIRequest.set_default_settings(api_key=u'YOURKEY', minimum_probability=None,
    show_sources=None, minimum_match=None, hide_sponsored=None, live_feeds=None, use_https=True)

Ruby

Pipl.configure do |c|
  c.api_key = 'YOURKEY'
  c.show_sources = 'all'
  c.minimum_probability = 0.7
  c.minimum_match = 0.5
  c.strict_validation = true
end

Java

import com.pipl.api.search.SearchAPIRequest;
import com.pipl.api.search.SearchConfiguration;

SearchConfiguration defaultConfiguration = SearchAPIRequest.getDefaultConfiguration();
defaultConfiguration.protocol = "https";
defaultConfiguration.apiKey = "YOURKEY";
defaultConfiguration.minimumProbability = null;
defaultConfiguration.showSources = null;
defaultConfiguration.possibleResults = null;
defaultConfiguration.hideSponsored = null;
defaultConfiguration.liveFeeds = null;

PHP

<?php

PiplApi_SearchAPIRequest::get_default_configuration()->api_key = "YOURKEY";
PiplApi_SearchAPIRequest::get_default_configuration()->minimum_probability = 0.9;
PiplApi_SearchAPIRequest::get_default_configuration()->minimum_match = 0.8;
PiplApi_SearchAPIRequest::get_default_configuration()->hide_sponsored = true;
PiplApi_SearchAPIRequest::get_default_configuration()->live_feeds = false;
PiplApi_SearchAPIRequest::get_default_configuration()->use_https = true;
PiplApi_SearchAPIRequest::get_default_configuration()->show_sources = "all";

C#

SearchConfiguration defaultConfiguration = SearchAPIRequest.DefaultConfiguration;
defaultConfiguration.UseHttps = true;
defaultConfiguration.ApiKey = "YOURKEY";
defaultConfiguration.MinimumProbability = null;
defaultConfiguration.ShowSources = null;
defaultConfiguration.MinimumMatch = null;
defaultConfiguration.HideSponsored = null;
defaultConfiguration.LiveFeeds = null;