Metadata-Version: 2.4
Name: datafiniti-sdk
Version: 0.1.1
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('name:"Starbucks" AND country:US')

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

# Paginate through large result sets
for record in sdk.paginate('name:"Starbucks"', page_size=100, max_records=500):
    print(record)
```

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

# 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
