Skip to main content

Official Python client for the People Data Labs API

Project description

People Data Labs Logo

People Data Labs Python Client

Official Python client for the People Data Labs API.

Repo Status   People Data Labs on PyPI   People Data Labs on PyPI   Tests Status

Table of Contents

🔧 Installation

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

    pip install peopledatalabs
    
  2. Sign up for a free PDL API key.

  3. Set your API key in the PDL_API_KEY environment variable.

🚀 Usage

First, create the PDLPY client:

from peopledatalabs import PDLPY


# specifying an API key
client = PDLPY(
    api_key="YOUR API KEY",
)

# or leave blank if you have PDL_API_KEY set in your environment or .env file
client = PDLPY()

Note: You can provide your API key directly in code, or alternatively set a PDL_API_KEY variable in your environment or .env file.

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

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

📘 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"})

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

peopledatalabs-1.1.8.tar.gz (13.7 kB view hashes)

Uploaded Source

Built Distribution

peopledatalabs-1.1.8-py3-none-any.whl (17.5 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page