Connecting to People Data Labs#
First Steps with People Data Labs#
Set up an account with People Data Labs.
???+ cost There are both free and paid options for this API.
Rate Limits
Your account plan tier will limit the number of requests each API key can make per minute. People Data Lab's documentation contains information on these limits.
How to Connect DataDistillr to People Data Labs#
To set up a data source connection for People Data Labs, you will need to have:
- A unique name for your data source connection to be used in queries
- An API token generated through your People Data Labs account
Data Source Form#
To locate the People Data Labs form, follow the steps in Connecting Your Data to DataDistillr. When you get to the window to choose the data source type, select API as shown below.
On the API screen, select People Data Labs from the list of API forms.
The following form will appear. Instructions are below on how to find the information required to fill each field on the People Data Labs API form.
Once you have filled out all the fields, press the green 'Save' button, and your API will be connected!
Name#
Enter any name that will help you recognize this data source within your query window.
Acceptable Characters Include
- lowercase alphanumeric characters
- underscores
API Key#
The API key is generated within your account page. The following steps will navigate you to its location. Once created, copy the key and enter it in the People Data Labs form under 'API Key'.
Click the API Keys button
This page contains the settings for your API token. You can modify the token's nickname and generate a new key with Roll This Key.
Endpoints#
The table below shows a list of endpoints available to connect within the DataDistillr application. If you need to connect to any endpoints not listed in the table below, please use the Custom API Form.
| Endpoint | Required | Optional | Description |
|---|---|---|---|
/person/enrich |
name first_name last_name middle_name location street_address locality region country postal_code company school phone email_hash profile lid birth_date min_likelihood required data_included include_if_matched titlecase pretty api_key |
Find the single best profile matching some attributes about a particular person. | |
/person/retrieve/{person_id} |
person_id | titlecase pretty api_key |
Directly lookup a specific profile using its PDL ID. |
/person/identify |
name first_name last_name middle_name location street_address locality region country postal_code company school phone email_hash profile lid birth_date min_likelihood required data_included include_if_matched titlecase pretty api_key |
Find the best selection of profiles associated with a particular set of attributes for a person or related persons. | |
/person/search |
query sql size scroll_token dataset data_include titlecase pretty api_key |
Find all the profiles for any number of persons that satisfy some search criteria. |
Nav Tree#
The endpoints above will display as follows in the nav tree once your API has successfully connected.
Sample Queries#
The following queries are intended to help you get started, and make life simpler querying within your API.
For the following examples, suppose that my People Data Labs API data source was called mypdlapi and I want to query
an endpoint. In the FROM clause, the endpoint goes after the People Data Labs data source name.
Enrich#
You can use the v5/person/enrich endpoint to enrich data on a person. The person enrichment API provides a one-to-one
match, providing up-to-date information on a unique individual.
SELECT *
FROM `mypdlapi`.`/person/enrich`
WHERE `first_name` = 'John'
AND `last_name` = 'Doe'
AND `postal_code` = '11111'
AND `phone` = '555-123-4567' LIMIT 100
Retrieve#
The Person Retrieve API allows you to use a PDL Person ID (like qEnOZ5Oh0poWnQ1luFBfVw_0000) to get back the data
associated with that ID. A PDL ID is a unique and permanent identifier for each record in our dataset, and so this
endpoint allows you to directly retrieve the data for the exact record you are interested in.
SELECT *
FROM `mypdlapi`.`/person/retrieve/:person_id`
WHERE `person_id` = 'qEnOZ5Oh0poWnQ1luFBfVw_0000' LIMIT 100
Identify#
The Identify API allows you to use broad search inputs to recover multiple records from our person dataset. In particular, this endpoint enables functionality such as searching by just single identifying attribute (such as name, email, phone number, company, school, or location) in addition to using any combination of these attributes.
SELECT *
FROM `mypdlapi`.`/person/identify`
WHERE `first_name` = 'John'
AND `last_name` = 'Doe'
AND `postal_code` = '11111'
AND `phone` = '555-123-4567' LIMIT 100
Search#
You can use the v5/person/search endpoint to write queries (in Elasticsearch or SQL format) against the dataset and
return any profiles that match those queries. People Data Lab's Search API is perfect for finding specific segments of
people that you need in order to power your projects and products.