datafiniti-sdk 0.1.8

Python SDK for Datafiniti Data APIs (Business, People, Property, Product)

Datafiniti SDK

Python SDK for the Datafiniti Data APIs — Business, People, Property, and Product data.

Installation

pip install datafiniti-sdk

Authentication

All SDK classes require a Datafiniti API key. You can pass it directly or set it as an environment variable:

export DATAFINITI_API_KEY="your_api_key_here"

Quick Start

from datafiniti import DatafinitiBusinessSDK, DatafinitiPeopleSDK, PropertyDataSDK, DatafinitiProductSDK

# Initialize from environment variable
sdk = PropertyDataSDK.from_env()

# Or pass the key directly
sdk = PropertyDataSDK(api_key="your_api_key_here")

Business Data

from datafiniti import DatafinitiBusinessSDK

sdk = DatafinitiBusinessSDK.from_env()

# Search by name
results = sdk.search_by_name("Starbucks", city="Seattle", num_records=5)

# Count matching records
count = sdk.count("country:US AND categories:(restaurants)")

# Build a custom query
query = sdk.query().country("US").categories(["restaurants"]).build()
results = sdk.search(query, num_records=10)

# Paginate through large result sets
for record in sdk.paginate('country:"US" AND province:"TX"', page_size=10, max_records=50):
    print(record)

# Search by geolocation — businesses within 10 miles of a coordinate
# geoLocation format: [Longitude, Latitude, Distance, Unit]
# Supported units: m, mi, ft, yd, mm, km, NM, cm
results = sdk.geolocation(
    longitude=-97.7430600,
    latitude=30.2671500,
    distance=10,
    unit="mi",
    num_records=3,
)

# Or use the query builder directly for geolocation
query = (
    sdk.query()
    .geo_location(-97.7430600, 30.2671500, 10, "mi")
    .build()
)
results = sdk.search(query, num_records=10)

# Use a named view to control which fields are returned
# Options: "default", "business_all_nested", "business_basic",
#          "business_flat_menus", "business_flat_reviews", "business_no_reviews"
results = sdk.search(
    query='country:"US" AND province:"TX"',
    num_records=5,
    view="business_flat_reviews",
)

People Data

from datafiniti 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)

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

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

# Search by email
results = sdk.search('emails:"[e-mail]"', num_records=1)

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

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

# Use a custom view to limit which fields are returned
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"},
]
results = sdk.search(
    query="country:US AND province:TX AND city:kingwood AND propertiesRepresented:*",
    num_records=5,
    view=view,
)

Property Data

from datafiniti import PropertyDataSDK

sdk = PropertyDataSDK.from_env()

# Search by address
results = sdk.search_by_address("123 Main St", postal_code="78701", num_records=1)

# Search by geolocation — properties within 10 miles of a coordinate
# Supported units: m, mi, ft, yd, mm, km, NM, cm
results = sdk.geolocation(
    longitude=-97.7430600,
    latitude=30.2671500,
    distance=10,
    unit="mi",
    num_records=10,
)

# Or use the query builder directly for geolocation
query = (
    sdk.query()
    .geo_location(-97.7430600, 30.2671500, 10, "mi")
    .most_recent_status("For Sale")
    .build()
)
results = sdk.search(query, num_records=10)

# Find properties for sale
results = sdk.for_sale(
    postal_codes=["78701", "78702"],
    property_types=["Single Family Residential"],
    num_records=20
)

# Count matching records
count = sdk.count('country:US AND mostRecentStatus:"For Sale"')

# Paginate through results
for record in sdk.paginate('country:US AND mostRecentStatus:"For Sale"', page_size=100):
    print(record["address"])

Product Data

from datafiniti import DatafinitiProductSDK

sdk = DatafinitiProductSDK.from_env()

# Search by product name
results = sdk.search_by_name("iPhone 15", brand="Apple", num_records=10)

# Count matching records
count = sdk.count('brand:"Apple"')

Common Methods

All four SDK classes inherit these methods:

Method	Description
search(query, num_records)	Search and return up to num_records results
count(query)	Return the total number of matching records
paginate(query, page_size, max_records)	Generator that yields records page by page
query()	Returns a query builder for the data type

Error Handling

from datafiniti import DatafinitiAPIError

try:
    results = sdk.search("country:US", num_records=10)
except DatafinitiAPIError as e:
    print(f"API error {e.status_code}: {e.message}")

Requirements

• Python 3.9+
• requests >= 2.31.0

License

MIT