Metadata-Version: 2.4
Name: addressverify
Version: 0.1.0
Summary: Official Python SDK for the AddressVerify API: validate residential addresses, classify home types, and get property values.
Project-URL: Homepage, https://addressverify.io
Project-URL: Documentation, https://addressverify.io/docs
Project-URL: Repository, https://github.com/AddressVerify-io/addressverify-python
Project-URL: Issues, https://github.com/AddressVerify-io/addressverify-python/issues
Author-email: AddressVerify <support@addressverify.io>
License: MIT
License-File: LICENSE
Keywords: address validation,address verification,addressverify,api,home value,property data,real estate api,sdk,usps
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Requires-Dist: requests>=2.25
Description-Content-Type: text/markdown

# AddressVerify Python SDK

Official SDK for the [AddressVerify](https://addressverify.io) API: validate U.S. residential
addresses, classify home types, and get estimated property values in real time.

[![PyPI](https://img.shields.io/pypi/v/addressverify.svg)](https://pypi.org/project/addressverify/)
[![license](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)

- 🏠 **Address validation**: confirm an address is a real, deliverable U.S. residence
- 🏷️ **Home-type classification**: `SINGLE_FAMILY`, `MULTI_FAMILY`, `APARTMENT`, `CONDO`, `TOWNHOUSE`, `MANUFACTURED`, `LOT`
- 💰 **Property values**: estimated home value, plus optional expanded property data
- 🐍 **Typed**: `TypedDict` response types and full type hints

## Installation

```bash
pip install addressverify
```

## Get an API key

Create a free account at **[app.addressverify.io](https://app.addressverify.io/user/register)** and copy your API key from the dashboard. The free tier includes 50 free API calls to get started.

## Quick start

```python
from addressverify import AddressVerify

av = AddressVerify(api_key="YOUR_API_KEY")

# Single-line address
result = av.verify("123 Main St, New York, NY 10001")

print(result["addressValid"])  # True
print(result["homeType"])      # "SINGLE_FAMILY"
print(result["homeValue"])     # 273900
```

### Multi-line address

```python
result = av.verify(
    street="20 Marie St",
    city="Iberia",
    state="MO",
    zip="65486",
)
```

### Expanded property data

Pass `expanded=True` to receive parsed address components, property details, tax
assessment, and listing data (available on all plans at no extra cost):

```python
result = av.verify("20 Marie St, Iberia, MO 65486", expanded=True)

print(result["propertyInfo"]["bedrooms"])         # 4
print(result["taxAssessment"]["taxAssessedValue"]) # 150210
print(result["listing"]["listingStatus"])         # "recentlySold"
```

## Response shape

```jsonc
{
  "address": "20 Marie St, Iberia, MO 65486",
  "addressValid": true,
  "homeType": "SINGLE_FAMILY",
  "homeValue": 371000,

  // present only with expanded=True
  "addressInfo":   { "streetAddress": "20 Marie St", "zipcode": "65486", "city": "Iberia", "state": "MO" },
  "propertyInfo":  { "bathrooms": 2, "bedrooms": 4, "livingArea": 2072, "yearBuilt": 2001, "lotSize": "1.84 acres" },
  "taxAssessment": { "taxAssessedValue": 150210, "taxAssessmentYear": "2024" },
  "listing":       { "lastSoldDate": "2025-05-22", "isPreforeclosureAuction": false, "listingStatus": "recentlySold" }
}
```

## Error handling

Non-2xx responses raise `AddressVerifyError` with the HTTP `status_code` and parsed `body`:

```python
from addressverify import AddressVerify, AddressVerifyError

av = AddressVerify(api_key="YOUR_API_KEY")

try:
    av.verify("not a real address")
except AddressVerifyError as err:
    print(err.status_code)  # e.g. 422
    print(err.body)         # API error payload
```

| Status | Meaning |
| ------ | ------- |
| `400`  | Bad Request: invalid or missing parameters |
| `401`  | Unauthorized: invalid API key |
| `422`  | Invalid address (e.g. missing street number) |
| `429`  | Too Many Requests: rate limit exceeded |

## Usage as a context manager

```python
with AddressVerify(api_key="YOUR_API_KEY") as av:
    result = av.verify("123 Main St, New York, NY 10001")
```

## Roadmap

- **Home Verify** (homeowner + person & property lookup, `…/isHomeOwner/homeOwner`): coming to the SDK. Already available on the [REST API](https://addressverify.io/docs).

## Links

- 🌐 Website: <https://addressverify.io>
- 📚 API docs: <https://addressverify.io/docs>
- 🔑 Get an API key: <https://app.addressverify.io/user/register>

## License

MIT © AddressVerify
