Metadata-Version: 2.4
Name: addresscomplete
Version: 1.0.0
Summary: A Python client for the Canada Post AddressComplete API
Project-URL: Homepage, https://github.com/dellwood546/AddressComplete
Project-URL: Repository, https://github.com/dellwood546/AddressComplete
Project-URL: Issues, https://github.com/dellwood546/AddressComplete/issues
Author-email: Darian Elwood <dellwood546@gmail.com>
License: GPL-3.0
License-File: LICENSE
Keywords: address,address-autocomplete,address-validation,addresscomplete,canada-post
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.7
Requires-Dist: requests>=2.32.3
Description-Content-Type: text/markdown

# AddressComplete

A Python client library for the Canada Post AddressComplete API. This library provides a simple interface for address autocomplete and validation using the Canada Post AddressComplete service.

## Features

- **Address Search**: Find address suggestions based on search terms
- **Address Retrieval**: Retrieve detailed address information using address IDs
- **Error Handling**: Comprehensive error handling with specific exception types for different API error codes
- **Easy to Use**: Simple, intuitive API design

## Installation

Install from PyPI (when available):

```bash
pip install AddressComplete
```

Or install from source:

```bash
git clone https://github.com/dellwood546/AddressComplete.git
cd AddressComplete
pip install .
```

## Requirements

- Python 3.7 or higher
- requests library

## Getting Started

To use AddressComplete, you'll need a Canada Post AddressComplete API key. You can obtain one from [Canada Post](https://www.canadapost-postescanada.ca/cpc/en/business/marketing/campaigns/addresscomplete.page).

### Basic Usage

```python
from addresscomplete import AddressComplete

# Initialize the client with your API key
client = AddressComplete("your-api-key-here")

# Search for addresses
results = client.find("123 Main St, Toronto")
print(results)

# Retrieve detailed address information
address_id = "CA|CP|ENG|3X1-R2J"
details = client.retrieve(address_id)
print(details)
```

### Advanced Usage

```python
from addresscomplete import AddressComplete, FindError, RetrieveError

client = AddressComplete("your-api-key-here")

try:
    # Search with custom parameters
    results = client.find(
        search_term="123 Main Street",
        country="CAN",
        max_suggestions=5,
        language_preference="en"
    )
    
    # Process results
    if results.get("Items"):
        for item in results["Items"]:
            print(f"ID: {item.get('Id')}, Description: {item.get('Description')}")
            
            # Retrieve full address details
            if item.get("Id"):
                try:
                    details = client.retrieve(item["Id"])
                    print(f"Full address: {details}")
                except RetrieveError as e:
                    print(f"Error retrieving address: {e}")
                    
except FindError as e:
    print(f"Error finding addresses: {e}")
```

## API Reference

### `AddressComplete(api_key)`

Initialize an AddressComplete client.

**Parameters:**
- `api_key` (str): Your Canada Post AddressComplete API key

### `find(search_term, country="CAN", max_suggestions=10, language_preference="en")`

Find address suggestions based on a search term.

**Parameters:**
- `search_term` (str): The address search term
- `country` (str, optional): The country code (default: "CAN")
- `max_suggestions` (int, optional): Maximum number of suggestions to return (default: 10)
- `language_preference` (str, optional): Language preference code, 2 or 4 digits (default: "en")

**Returns:**
- dict: JSON response containing address suggestions

**Raises:**
- `FindError`: If the API returns an error

### `retrieve(id)`

Retrieve detailed address information based on an address ID.

**Parameters:**
- `id` (str): The unique identifier for the address (obtained from `find()`)

**Returns:**
- dict: JSON response containing detailed address information

**Raises:**
- `RetrieveError`: If the API returns an error

## Error Handling

The library provides specific exception types for different error scenarios:

- `FindError`: Raised when the `find()` method encounters an error
- `RetrieveError`: Raised when the `retrieve()` method encounters an error

Both exceptions are subclasses of the base `ResponseError` class and provide detailed error information based on the API error codes.

## License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0). See the [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Issues

If you encounter any issues or have questions, please open an issue on the [GitHub repository](https://github.com/dellwood546/AddressComplete/issues).

## Author

Darian Elwood (dellwood546@gmail.com)
