People Data Labs Python Client

Official Python client for the People Data Labs API.

     

Table of Contents

• 🔧 Installation
• 🚀 Usage
• 🏝 Sandbox Usage
• 🌐 Endpoints
• 📘 Documentation
  • Upgrading to v2.X.X
  • Upgrading to v3.X.X
  • Upgrading to v4.X.X

🔧 Installation

1. Install from PyPi using pip, a package manager for Python.

   pip install peopledatalabs

2. Sign up for a free PDL API key.

🚀 Usage

First, create the PDLPY client:

from peopledatalabs import PDLPY


# specify your API key
client = PDLPY(
    api_key="YOUR API KEY",
)

Then, send requests to any PDL API Endpoint.

Getting Person Data

By Enrichment

result = client.person.enrichment(
    phone="4155688415",
    pretty=True,
)
if result.ok:
    print(result.text)
else:
    print(
        f"Status: {result.status_code};"
        f"\nReason: {result.reason};"
        f"\nMessage: {result.json()['error']['message']};"
    )

By Bulk Enrichment

result = client.person.bulk(
    required="emails AND profiles",
    requests=[
        {
            "metadata": {
                "user_id": "123"
            },
            "params": {
                "profile": ["linkedin.com/in/seanthorne"],
                "location": ["SF Bay Area"],
                "name": ["Sean F. Thorne"],
            }
        },
        {
            "metadata": {
                "user_id": "345"
            },
            "params": {
                "profile": ["https://www.linkedin.com/in/haydenconrad/"],
                "first_name": "Hayden",
                "last_name": "Conrad",
            }
        }
    ]
)
if result.ok:
    print(result.text)
else:
    print(
        f"Status: {result.status_code}"
        f"\nReason: {result.reason}"
        f"\nMessage: {result.json()['error']['message']}"
    )

By Search (Elasticsearch)

es_query = {
    "query": {
        "bool": {
            "must": [
                {"term": {"location_country": "mexico"}},
                {"term": {"job_title_role": "health"}},
            ]
        }
    }
}
data = {
    "query": es_query,
    "size": 10,
    "pretty": True,
    "dataset": "phone, mobile_phone",
}
result = client.person.search(**data)
if result.ok:
    print(result.text)
else:
    print(
        f"Status: {result.status_code}"
        f"\nReason: {result.reason}"
        f"\nMessage: {result.json()['error']['message']}"
    )

By Search (SQL)

sql_query = (
    "SELECT * FROM person"
    " WHERE location_country='mexico'"
    " AND job_title_role='health'"
    " AND phone_numbers IS NOT NULL;"
)
data = {
    "sql": sql_query,
    "size": 10,
    "pretty": True,
    "dataset": "phone, mobile_phone",
}
result = client.person.search(**data)
if result.ok:
    print(result.text)
else:
    print(
        f"Status: {result.status_code}"
        f"\nReason: {result.reason}"
        f"\nMessage: {result.json()['error']['message']}"
    )

By PDL_ID (Retrieve API)

result = client.person.retrieve(
    person_id="qEnOZ5Oh0poWnQ1luFBfVw_0000",
)
if result.ok:
    print(result.text)
else:
    print(
        f"Status: {result.status_code}"
        f"\nReason: {result.reason}"
        f"\nMessage: {result.json()['error']['message']}"
    )

By Fuzzy Enrichment (Identify API)

result = client.person.enrichment(
    name="sean thorne",
    pretty=True,
)
if result.ok:
    print(result.text)
else:
    print(
        f"Status: {result.status_code}"
        f"\nReason: {result.reason}"
        f"\nMessage: {result.json()['error']['message']}"
    )

Getting Company Data

By Enrichment

result = client.company.enrichment(
    website="peopledatalabs.com",
    pretty=True,
)
if result.ok:
    print(result.text)
else:
    print(
        f"Status: {result.status_code}"
        f"\nReason: {result.reason}"
        f"\nMessage: {result.json()['error']['message']}"
    )

By Bulk Enrichment

result = client.company.bulk(
    requests=[
        {
            "metadata": {
                "company_id": "123"
            },
            "params": {
                "profile": "linkedin.com/company/peopledatalabs",
            }
        },
        {
            "metadata": {
                "company_id": "345"
            },
            "params": {
                "profile": "https://www.linkedin.com/company/apple/",
            }
        }
    ]
)
if result.ok:
    print(result.text)
else:
    print(
        f"Status: {result.status_code}"
        f"\nReason: {result.reason}"
        f"\nMessage: {result.json()['error']['message']}"
    )

By Search (Elasticsearch)

es_query = {
    "query": {
        "bool": {
            "must": [
                {"term": {"tags": "big data"}},
                {"term": {"industry": "financial services"}},
                {"term": {"location.country": "united states"}},
            ]
        }
    }
}
data = {
    "query": es_query,
    "size": 10,
    "pretty": True,
}
result = client.company.search(**data)
if result.ok:
    print(result.text)
else:
    print(
        f"Status: {result.status_code}"
        f"\nReason: {result.reason}"
        f"\nMessage: {result.json()['error']['message']}"
    )

By Search (SQL)

sql_query = (
    "SELECT * FROM company"
    " WHERE tags='big data'"
    " AND industry='financial services'"
    " AND location.country='united states';"
)
data = {
    "sql": sql_query,
    "size": 10,
    "pretty": True,
}
result = client.company.search(**data)
if result.ok:
    print(result.text)
else:
    print(
        f"Status: {result.status_code}"
        f"\nReason: {result.reason}"
        f"\nMessage: {result.json()['error']['message']}"
    )

Using supporting APIs

Get Autocomplete Suggestions

result = client.autocomplete(
    field="title",
    text="full",
    size=10,
)
if result.ok:
    print(result.text)
else:
    print(
        f"Status: {result.status_code}"
        f"\nReason: {result.reason}"
        f"\nMessage: {result.json()['error']['message']}"
    )

Clean Raw Company Strings

result = client.company.cleaner(
    name="peOple DaTa LabS",
)
if result.ok:
    print(result.text)
else:
    print(
        f"Status: {result.status_code}"
        f"\nReason: {result.reason}"
        f"\nMessage: {result.json()['error']['message']}"
    )

Clean Raw Location Strings

result = client.location.cleaner(
    location="455 Market Street, San Francisco, California 94105, US",
)
if result.ok:
    print(result.text)
else:
    print(
        f"Status: {result.status_code}"
        f"\nReason: {result.reason}"
        f"\nMessage: {result.json()['error']['message']}"
    )

Clean Raw School Strings

result = client.school.cleaner(
    name="university of oregon",
)
if result.ok:
    print(result.text)
else:
    print(
        f"Status: {result.status_code}"
        f"\nReason: {result.reason}"
        f"\nMessage: {result.json()['error']['message']}"
    )

Get Job Title Enrichment

result = client.job_title(
    job_title="data scientist",
)
if result.ok:
    print(result.text)
else:
    print(
        f"Status: {result.status_code}"
        f"\nReason: {result.reason}"
        f"\nMessage: {result.json()['error']['message']}"
    )

Get Skill Enrichment

result = client.skill(
    skill="c++",
)
if result.ok:
    print(result.text)
else:
    print(
        f"Status: {result.status_code}"
        f"\nReason: {result.reason}"
        f"\nMessage: {result.json()['error']['message']}"
    )

Get IP Enrichment

result = client.ip(
    ip="72.212.42.169",
)
if result.ok:
    print(result.text)
else:
    print(
        f"Status: {result.status_code};"
        f"\nReason: {result.reason};"
        f"\nMessage: {result.json()['error']['message']};"
    )

🏝 Sandbox Usage

To enable sandbox usage, use the sandbox flag on PDLPY

PDLPY(sandbox=True)

🌐 Endpoints

Person Endpoints

API Endpoint	PDLPY Function
Person Enrichment API	PDLPY.person.enrichment(**params)
Person Bulk Enrichment API	PDLPY.person.bulk(**params)
Person Search API	PDLPY.person.search(**params)
Person Retrieve API	PDLPY.person.retrieve(**params)
Person Identify API	PDLPY.person.identify(**params)

Company Endpoints

API Endpoint	PDLPY Function
Company Enrichment API	PDLPY.company.enrichment(**params)
Company Bulk Enrichment API	PDLPY.company.bulk(**params)
Company Search API	PDLPY.company.search(**params)

Supporting Endpoints

API Endpoint	PDLJS Function
Autocomplete API	PDLPY.autocomplete(**params)
Company Cleaner API	PDLPY.company.cleaner(**params)
Location Cleaner API	PDLPY.location.cleaner(**params)
School Cleaner API	PDLPY.school.cleaner(**params)
Job Title Enrichment API	PDLPY.job_title(**params)
Skill Enrichment API	PDLPY.skill(**params)
IP Enrichment API	PDLPY.ip(**params)

📘 Documentation

All of our API endpoints are documented at: https://docs.peopledatalabs.com/

These docs describe the supported input parameters, output responses and also provide additional technical context.

As illustrated in the Endpoints section above, each of our API endpoints is mapped to a specific method in the PDLPY class. For each of these class methods, all function inputs are mapped as input parameters to the respective API endpoint, meaning that you can use the API documentation linked above to determine the input parameters for each endpoint.

As an example:

The following is valid because name is a supported input parameter to the Person Identify API:

PDLPY().person.identify({"name": "sean thorne"})

Conversely, this would be invalid because fake_parameter is not an input parameter to the Person Identify API:

PDLPY().person.identify({"fake_parameter": "anything"})

Upgrading to v2.X.X

NOTE: When upgrading to v2.X.X from vX.X.X and below, the minimum required python version is now 3.8.

Upgrading to v3.X.X

NOTE: When upgrading to v3.X.X from vX.X.X and below, the minimum required pydantic version is now 2.

Upgrading to v4.X.X

NOTE: When upgrading to v4.X.X from vX.X.X and below, we no longer auto load the API key from the environment variable PDL_API_KEY. You must now pass the API key as a parameter to the PDLPY class.