Metadata-Version: 2.4
Name: datafiniti-sdk
Version: 0.1.4
Summary: Python SDK for Datafiniti Data APIs (Business, People, Property, Product)
Author-email: Leonard Trahan <leonard@datafiniti.co>
License: MIT
Project-URL: Homepage, https://github.com/datafiniti/DatafinitiSDK
Project-URL: Bug Tracker, https://github.com/datafiniti/DatafinitiSDK/issues
Keywords: datafiniti,api,sdk,business,property,people,product
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: ==3.9.*
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"

# Datafiniti SDK

[![PyPI version](https://badge.fury.io/py/datafiniti-sdk.svg)](https://pypi.org/project/datafiniti-sdk/)

Python SDK for the [Datafiniti](https://datafiniti.co) Data APIs — Business, People, Property, and Product data.

## Installation

```bash
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:

```bash
export DATAFINITI_API_KEY="your_api_key_here"
```

## Quick Start

```python
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

```python
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

```python
from datafiniti import DatafinitiPeopleSDK

sdk = DatafinitiPeopleSDK.from_env()

# Search by name
results = sdk.search_by_name("John Smith", city="Austin", num_records=10)

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

## Property Data

```python
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

```python
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

```python
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
