addresscomplete 1.0.0

A Python client for the Canada Post AddressComplete API

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

pip install AddressComplete

Or install from source:

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.

Basic Usage

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

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 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.

Author

Darian Elwood ([e-mail])