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:

from piplapis.search import SearchAPIRequest
request = SearchAPIRequest(email=u'[email protected]', api_key='YOURKEY')

require 'pipl'
response = Pipl::client.search email: '[email protected]', api_key: 'YOURKEY'

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("[email protected]").firstName("Clark").lastName("Kent").configuration(configuration).build();

<?php

require_once './piplapis/search.php';

$configuration = new PiplApi_SearchRequestConfiguration();
$configuration->use_https = true;
$configuration->api_key = 'YOURKEY';
  
$request = new PiplApi_SearchAPIRequest(array('email' => '[email protected]',
'first_name' => 'Clark',
'last_name' => 'Kent'), $configuration);

?>

SearchConfiguration searchConfiguration = new SearchConfiguration(apiKey: "YOURKEY",useHttps: true);
SearchAPIRequest request = new SearchAPIRequest(email: "[email protected]",
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:

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')

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'

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
$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;

SearchConfiguration searchConfiguration = new SearchConfiguration(apiKey: "YOURKEY",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

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

begin
  response = Pipl::client.search email: '[email protected]'
rescue Pipl::Client::APIError => e
  puts e.status_code, e.message
end

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
try {
    $response = $request->send();
} catch (PiplApi_SearchAPIError $e) {
    print $e->getMessage();
}

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

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

request.send_async(my_callback)
do_other_things()

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

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();
}

# Not available in PHP

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:

>>> 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)'

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)'

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
print $response->person->addresses[0]; // 10-1 Hickory Lane, Smallville, Kansas

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:

>>> 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")]

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

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

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

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

>>> 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'

response = Pipl::client.search email: '[email protected]', 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'

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

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:

>>> 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>]

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

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

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

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:

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

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

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

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

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("[email protected]").build();
System.out.println(email.username());
// Output: "clark.kent"

<?php
print $response->address()->state; // KS
print $response->address()->state_full(); // Kansas
print $response->email(); // [email protected]
print $response->email()->username; // clark.kent

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: "[email protected]");
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.

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)

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

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

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";

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;