Address Validation for International Addresses

3.1.1 · active · verified Fri Apr 17

google-i18n-address provides address validation helpers leveraging Google's international address database. It helps in validating, normalizing, and latinizing addresses for various countries. The library is currently at version 3.1.1 and receives updates typically for database rule changes or minor packaging improvements.

Common errors

```
NameError: name 'InvalidAddress' is not defined
```
cause Your code is using the old exception name `InvalidAddress` with version 3.0.0 or newer of the library.

fix Change `InvalidAddress` to `InvalidAddressError` and ensure it's imported correctly: `from i18naddress.errors import InvalidAddressError`.
```
AttributeError: 'list' object has no attribute 'startswith'
```
cause Your code expects `ValidationRules.postal_code_examples` to be a string, but it is now a list of strings in versions 2.2.0 and later.

fix Modify your code to treat `postal_code_examples` as a list. For example, access `rules.postal_code_examples[0]` for the first example or iterate over the list.
```
ModuleNotFoundError: No module named 'google_i18n_address'
```
cause You are attempting to import the library using `google_i18n_address`, but the correct import path is `i18naddress`.

fix Replace all instances of `import google_i18n_address` or `from google_i18n_address import ...` with `import i18naddress` or `from i18naddress import ...`.

Warnings

breaking The exception class `InvalidAddress` was renamed to `InvalidAddressError` for PEP8 compliance.
Fix: Update your exception handling from `except InvalidAddress:` to `except InvalidAddressError:` and ensure you import `InvalidAddressError` from `i18naddress.errors`.
breaking The `ValidationRules.postal_code_examples` attribute changed its type from a string to a list of strings.
Fix: If your code expects `postal_code_examples` to be a string, update it to handle a list, e.g., `rules.postal_code_examples[0]` for the first example or iterate over the list.
gotcha The Python package name is `google-i18n-address` on PyPI, but its top-level import is `i18naddress`.
Fix: Always use `import i18naddress` or `from i18naddress import ...` in your code, not `google_i18n_address`.
gotcha Validation logic for non-required fields changed. Empty fields that are not explicitly required will no longer be marked as invalid, even if a list of choices for that field exists.
Fix: Review any custom validation logic that relies on empty non-required fields being flagged as invalid when a choice list is present. Adjust expectations or add explicit checks if needed.

Install

pip install google-i18n-address Install stable release

Imports

Address
wrong:
```
from google_i18n_address import Address
```
correct:
```
from i18naddress import Address
```
The PyPI package `google-i18n-address` is imported as `i18naddress`.
AddressValidator
wrong:
```
from google_i18n_address import AddressValidator
```
correct:
```
from i18naddress import AddressValidator
```
The PyPI package `google-i18n-address` is imported as `i18naddress`.
get_validation_rules
wrong:
```
from google_i18n_address import get_validation_rules
```
correct:
```
from i18naddress import get_validation_rules
```
The PyPI package `google-i18n-address` is imported as `i18naddress`.
InvalidAddressError
wrong:
```
from i18naddress.errors import InvalidAddress
```
correct:
```
from i18naddress.errors import InvalidAddressError
```
Exception name changed in v3.0.0. The package name is `i18naddress`.

Quickstart

This quickstart demonstrates how to validate an international address using Address, AddressValidator, and get_validation_rules. It also shows how to normalize an address object.

from i18naddress import Address, AddressValidator, get_validation_rules

address_data = {
    'country_code': 'US',
    'street_address': '1600 Amphitheatre Pkwy',
    'city': 'Mountain View',
    'postal_code': '94043',
    'country_area': 'CA'
}

# Create an Address object
address = Address(**address_data)

# Get validation rules for the address's country
rules = get_validation_rules(address_data)

# Validate the address
errors = AddressValidator().validate(address, rules)

if errors:
    print(f"Validation errors: {errors}")
else:
    print("Address is valid.")

# Example of getting normalized address
normalized_address = address.normalize()
print(f"Normalized address: {normalized_address.as_dict()}")

view raw JSON →