People Data SDK

from datafiniti.people import DatafinitiPeopleSDK

sdk = DatafinitiPeopleSDK.from_env()

# Search by name — first and last name are required separately
results = sdk.search_by_name("John", "Smith", city="Austin", num_records=10)

print("
=== NAME SEARCH TEST ===")
print("Matches:", results.get("num_found"))

records = results.get("records", [])

if records:
    person = records[0]
    print("
Person:")
    print(person.get("firstName"))
    print(person.get("lastName"))
    print(person.get("city"))
else:
    print("No person found.")

from datafiniti.people import DatafinitiPeopleSDK

sdk = DatafinitiPeopleSDK.from_env()

count = sdk.count('firstName:"John" AND lastName:"Smith" AND country:US')

print("
=== COUNT TEST ===")
print(f"People found: {count:,}")

from datafiniti.people import DatafinitiPeopleSDK

sdk = DatafinitiPeopleSDK.from_env()

# Build a contact info query — search by name, email, or peopleKey
query = (
    sdk.query()
    .first_name("Joe")
    .last_name("Curry")
    .country("US")
    .province("CO")
    .city("Denver")
    .build()
)

results = sdk.search(query, num_records=10)

print("
=== QUERY BUILDER TEST ===")
print(f"Total matches: {results.get('num_found'):,}")

for person in results.get("records", []):
    print(f"{person.get('firstName')} {person.get('lastName')} — {person.get('city')}")

from datafiniti.people import DatafinitiPeopleSDK

sdk = DatafinitiPeopleSDK.from_env()

# Search by email
results = sdk.search('emails:"someone@example.com"', num_records=1)

# Search by peopleKey (cross-referenced from property data)
results = sdk.search('keys:"nathan/sandel/us/tx/78704/412southcongressave"', num_records=1)

print("
=== EMAIL & KEY SEARCH ===")
for person in results.get("records", []):
    print(f"{person.get('firstName')} {person.get('lastName')}")
    print(f"--emails: {person.get('emails')}")
    print(f"--keys: {person.get('keys')}")

from datafiniti.people import DatafinitiPeopleSDK

sdk = DatafinitiPeopleSDK.from_env()

print("
=== PAGINATION TEST ===")

records_seen = 0

# Paginate through large result sets
for person in sdk.paginate(
    query="country:US AND jobTitle:*",
    page_size=10,
    max_records=50,
):
    records_seen += 1
    print(person.get("firstName"), person.get("lastName"), person.get("jobTitle"))

print(f"
Total Retrieved: {records_seen}")

"""
People Views Example: Limit Returned Fields

Uses a custom view to fetch only the fields needed to build a lightweight
contact list — first name, last name, email, city, and country — for people
who represent properties in a target market.
"""

from datafiniti.people import DatafinitiPeopleSDK

# ---------------------------------------------------------------------------
# View options
#
# OPTION 1 (used below): Custom inline view
#   Pass a list of field objects directly in the request. No setup required.
#   Each object can set "flatten" and "sub_fields" to control nested output.
#
# OPTION 2: Premade (named) view — pass a string instead of a list.
#   "default"   All fields (same as omitting view entirely).
#   Reference: https://docs.datafiniti.co/docs/available-views-for-people-data
# ---------------------------------------------------------------------------

PEOPLE_VIEW = [
    {"flatten": False, "sub_fields": [], "name": "firstName"},
    {"flatten": False, "sub_fields": [], "name": "lastName"},
    {"flatten": False, "sub_fields": [], "name": "emails"},
    {"flatten": False, "sub_fields": [], "name": "city"},
    {"flatten": False, "sub_fields": [], "name": "country"},
]

sdk = DatafinitiPeopleSDK.from_env()

results = sdk.search(
    query="country:US AND province:TX AND city:kingwood AND propertiesRepresented:*",
    num_records=5,
    view=PEOPLE_VIEW,
)

print("
=== PEOPLE VIEWS ===")
print(f"Total matches: {results.get('num_found'):,}
")

for person in results.get("records", []):
    print(f"Name:    {person.get('firstName', 'N/A')} {person.get('lastName', 'N/A')}")
    print(f"Email:   {person.get('emails', ['N/A'])[0] if person.get('emails') else 'N/A'}")
    print(f"City:    {person.get('city', 'N/A')}")
    print(f"Country: {person.get('country', 'N/A')}")
    print()