Skip to content

Latest commit

 

History

History
501 lines (425 loc) · 13.8 KB

README.md

File metadata and controls

501 lines (425 loc) · 13.8 KB
Raw

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="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.