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.

🚀 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="varun villait",
    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 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)
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": "varun villait"})

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.

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-6.3.1.tar.gz (13.9 kB view details)

Uploaded Source

Built Distribution

peopledatalabs-6.3.1-py3-none-any.whl (18.0 kB view details)

Uploaded Python 3

File details

Details for the file peopledatalabs-6.3.1.tar.gz.

File metadata

  • Download URL: peopledatalabs-6.3.1.tar.gz
  • Upload date:
  • Size: 13.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.1.3 CPython/3.12.3 Linux/6.11.0-1015-azure

File hashes

Hashes for peopledatalabs-6.3.1.tar.gz
Algorithm Hash digest
SHA256 02dc3e6286720e651ff04dc2ada383c4292fd43d81972827c6e1d3e2a5331b5b
MD5 83d42805fafd5075748edf4ea39c77d1
BLAKE2b-256 97b7b9e11eac23c4e5ff89bd8ca621982e3adc265d0f3ef95265fcddea1be77a

See more details on using hashes here.

File details

Details for the file peopledatalabs-6.3.1-py3-none-any.whl.

File metadata

  • Download URL: peopledatalabs-6.3.1-py3-none-any.whl
  • Upload date:
  • Size: 18.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/2.1.3 CPython/3.12.3 Linux/6.11.0-1015-azure

File hashes

Hashes for peopledatalabs-6.3.1-py3-none-any.whl
Algorithm Hash digest
SHA256 ea792143287fb8cb32ec35ffecac848c6eafb273dd5073dcccf45f4fc617ec8e
MD5 67da0edf50836938d14fc9abaa659727
BLAKE2b-256 7b0bf16596414ed912b7770ea542128d74c65d4c621f370e31bf5d9ed5ef4c6e

See more details on using hashes here.

Supported by

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