usaddress

library0.5.16pypypi✓ verified 25d ago

USaddress is a Python library designed for parsing unstructured United States address strings into their individual components, employing advanced Natural Language Processing (NLP) methods. It utilizes a probabilistic model, specifically Conditional Random Fields, to make educated guesses in identifying address parts, even in complex cases. The library's current version is 0.5.16, and it is actively maintained.

data ai-ml

pip install usaddress

github ↗package ↗

INSTALL

IMPORT

SIG · USADDRESS

usaddress

datapythonv0.5.16

Install

1.7s avg

Import

39ms

Disk

22MB

Pass rate

10/ 10

Env Coverage10 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.5.16 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

installs and imports cleanly · install 0.0s · import 0.042s · 25.4MB

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 1.7s · import 0.036s · 23MB

22MB installed

● package 22MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

usaddress

✓ import usaddress

The library is imported directly as 'usaddress'.

This example demonstrates both the `parse()` method, which returns a list of (value, label) tuples, and the `tag()` method, which returns a more structured `OrderedDict` of components and an inferred address type.

import usaddress address_string = "123 Main St. Suite 100 Chicago, IL 60601" # The .parse() method returns a list of (value, label) tuples parsed_address = usaddress.parse(address_string) print("Parsed (tuples):") print(parsed_address) # The .tag() method returns an OrderedDict of components and an address type tagged_address, address_type = usaddress.tag(address_string) print("\nTagged (OrderedDict & Type):") print(tagged_address) print(f"Address Type: {address_type}")

Debug

Known issues

gotchaThe `usaddress.tag()` method may raise a `RepeatedLabelError` if an address string contains multiple components that are assigned the same label and cannot be logically concatenated into a single value (e.g., two distinct 'StreetName' labels without an 'IntersectionSeparator'). This often indicates an ambiguous or improperly formatted input address.

fix

Catch `RepeatedLabelError` when using `tag()` and consider using `parse()` for more granular (though less aggregated) output, or preprocess ambiguous input strings.

affects: All versions 0.5.x and likely earlier

gotchausaddress is designed specifically for 'United States address strings'. Attempting to parse international addresses will likely result in incorrect component labeling or parsing failures. The underlying model is trained on US address patterns.

fix

Ensure input addresses are strictly within the United States. For international address parsing, use a library specifically designed for global addresses (e.g., libpostal Python bindings).

affects: All versions

gotchaThe library uses a probabilistic model to identify address components, but it 'cannot identify address components with perfect accuracy, nor can it verify that a given address is correct/valid.' It provides structured components but does not perform address validation (e.g., checking if an address is mailable or exists).

fix

Do not rely on usaddress for address validation. For validation, integrate with a dedicated address verification service (e.g., USPS API, SmartyStreets, etc.) after parsing with usaddress.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'usaddress'

The 'usaddress' library has not been installed in the current Python environment.

fix

Install the library using pip: `pip install usaddress`

IOError: [Errno 2] No such file or directory: 'tagger.crfsuite'

The Conditional Random Field (CRF) model file, 'tagger.crfsuite', which 'usaddress' relies on, cannot be found, often due to an incomplete or corrupted installation.

fix

Reinstall 'usaddress' to ensure all model dependencies are correctly placed: `pip uninstall usaddress && pip install usaddress`

TypeError: expected string or bytes-like object

The `usaddress.tag()` function received an input that was not a string or bytes-like object (e.g., None, an integer, or a list).

fix

Ensure the input passed to `usaddress.tag()` is a valid string: `usaddress.tag(str(my_variable))` or validate input: `if isinstance(my_variable, str): usaddress.tag(my_variable)`

AttributeError: module 'usaddress' has no attribute 'tags'

The code is attempting to call a function or attribute (like 'tags' or 'parse_address') that does not exist within the 'usaddress' module.

fix

Use the correct function name `usaddress.tag()` or its alias `usaddress.parse()` to parse an address string.

Upgrade

Version history

0.5.16latest on PyPI · released Aug 7, 2025

Audit

Dependencies

python-crfsuiterequiredCore dependency for the Conditional Random Fields model used in parsing.

Agent activity

19 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/datamade/usaddress ↗

packagehttps://pypi.org/project/usaddress/ ↗