Searching by Address

This guide walks through the best practices for using an address or location as an input parameter of a Search API query

Using the Address Parameters

The best way to include an address into an API query is to separate it into individual fields (house, street, city, state, country, zip_code). This ensures that the address is parsed correctly.

If it is not possible to separate the address into individual fields, there is also the option to use the raw address field to pass the full address. The Search API will do its best to interpret the address into the separate fields for the query. The address should be comma separated and follow the standard formatting of the country. If the address is outside of the US, you must include the two-digit country code at the end of the address for it to be parsed correctly. Check the query field in an API response to see how the API parsed your address and ensure that it was done correctly.

Below are some examples of addresses that can be parsed successfully by the Search API in the raw_address field:

510 S Clearwater Loop, Post Falls, ID, 83854, US
1600 Pennsylvania Avenue NW, Washington, DC 20500
2 Gabriel Avenue, 75008 Paris, FR

🚧 Meeting Minimum Search Criteria

In the US, a full street address (down to the house number) can be searched by itself. Outside the US, you must include at least one other required parameter in order to fulfil the minimum requirements for a valid search

Partial Addresses

Even if you do not have the full street address of a person, if you are able to include location information in a query in the form of a partial address, this can significantly improve your results.

For example, if you are searching by a combination of name + email address, but you have information on the country of these individuals, consider adding this information into the query using the country field. If you have details of location down to the state or city level, this will likely improve the results even further.

Examples

//Example 1: Country only
email=clark.kent@example.com&country=US

//Example 2: Country, State and City
email=clark.kent@example.com&country=US&state=NY&city=New York City

//Example 1: Country only
https://api.pipl.com/search/?key=YOUR-API-KEY&email=clark.kent@example.com&country-US

//Example 2: Country, State and City
https://api.pipl.com/search/?key=YOUR-API-KEY&email=clark.kent@example.com&country-US&state=NY&city=New York City

from piplapis.data import Person, Email, Address
from piplapis.search import SearchAPIRequest

#Example 1: Country only
fields = [Email(address='clark.kent@example.com'), Address(country='US')]
request = SearchAPIRequest(person=Person(fields=fields), api_key='YOUR-API-KEY')
response = request.send()

#Example 2: Country, State and City
fields = [Email(address='clark.kent@example.com'), Address(country='US', state='NY', city='New York City')]
request = SearchAPIRequest(person=Person(fields=fields), api_key='YOUR-API-KEY')
response = request.send()

require 'pipl'

#Example 1: Country only
person = Pipl::Person.new
person.add_field Pipl::Email.new(address: 'clark.kent@example.com')
person.add_field Pipl::Address.new(country: 'US')
response = Pipl::client.search person: person, api_key: 'YOUR-API-KEY'

#Example 2: Country, State and City
person = Pipl::Person.new
person.add_field Pipl::Email.new(address: 'clark.kent@example.com')
person.add_field Pipl::Address.new(country: 'US', state: 'NY', city: 'New York City')
response = Pipl::client.search person: person, api_key: 'YOUR-API-KEY'

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 = "YOUR-API-KEY";

//Example 1: Country only
List<Field> fields = new ArrayList<Field>();
fields.add(new Email.Builder().address("clark.kent@example.com").build());
fields.add(new Address.Builder().country("US").build());
Person person = new Person(fields);
SearchAPIRequest request = new SearchAPIRequest(person, configuration);
SearchAPIResponse response = request.send();

//Example 2: Country, State and City
fields = new ArrayList<Field>();
fields.add(new Email.Builder().address("clark.kent@example.com").build());
fields.add(new Address.Builder().country("US").state("NY").city("New York City").build());
person = new Person(fields);
request = new SearchAPIRequest(person, configuration);
response = request.send();

<?php

require_once './piplapis/search.php';

$configuration = new PiplApi_SearchRequestConfiguration();
$configuration->use_https = true;
$configuration->api_key = 'YOUR-API-KEY';

//Example 1: Country only
$fields = array(
    new PiplApi_Email(array("address" => "clark.kent@example.com")),
    new PiplApi_Address(array("country" => "US"))
);
$person = new PiplApi_Person($fields);
$request = new PiplApi_SearchAPIRequest(array('person' => $person), $configuration);
$response = $request->send();

//Example 2: Country, State and City
$fields = array(
    new PiplApi_Email(array("address" => "clark.kent@example.com")),
    new PiplApi_Address(array("country" => "US", "state" => "NY", "city" => "New York City"))
);
$person = new PiplApi_Person($fields);
$request = new PiplApi_SearchAPIRequest(array('person' => $person), $configuration);
$response = $request->send();

?>

using Pipl.APIs.Search;
using System.Collections.Generic;

SearchConfiguration searchConfiguration = new SearchConfiguration(
    apiKey: "YOUR-API-KEY",
    url: "api.pipl.com/search/",
    useHttps: true
);

//Example 1: Country only
List<Field> fields = new List<Field>()
{
    new Email(address: "clark.kent@example.com"),
    new Address(country: "US")
};
var person = new Person(fields);
SearchAPIRequest request = new SearchAPIRequest(
    person: person,
    requestConfiguration: searchConfiguration
);
var response = await request.SendAsync();

//Example 2: Country, State and City
fields = new List<Field>()
{
    new Email(address: "clark.kent@example.com"),
    new Address(country: "US", state: "NY", city: "New York City")
};
person = new Person(fields);
request = new SearchAPIRequest(
    person: person,
    requestConfiguration: searchConfiguration
);
response = await request.SendAsync();

Using the Address Parameters​

Partial Addresses​

Examples​

Using the Address Parameters

Partial Addresses

Examples