usaddress

What it is and what it does

usaddress is a Python library that breaks down unstructured US address strings into their component parts—street number, street name, city, state, ZIP code, and more—using a probabilistic model based on conditional random fields. It handles messy, real-world addresses that don't follow strict formatting rules, making educated guesses when components are ambiguous or malformed. The library provides two main methods: `parse()` returns a flat list of labeled components, while `tag()` merges consecutive components and returns a cleaner dictionary structure.

The package depends on python-crfsuite for its machine-learning backbone and probableparsing for feature extraction. It does not normalize addresses or verify their correctness—it only identifies and labels the parts. If you need normalized output, the documentation points to usaddress-scourgify as a complementary tool. The library is built on Parserator, a framework for training and improving probabilistic parsers, so you can add new training data if the model consistently fails on particular address patterns.

Use it for:

• Bulk import of address data from unstructured sources (web forms, PDFs, scanned documents) into a database with labeled fields.
• Data cleaning and standardization pipelines where addresses arrive in inconsistent formats from multiple sources.
• Building a web service or API that accepts free-form address input and returns structured components for downstream processing.
• Geocoding workflows where address components must be extracted before lookup in a geographic database.
• Training data generation for machine-learning models that require structured address features as input.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

usaddress parses unstructured US address strings into labeled components using a probabilistic model trained on conditional random fields, handling ambiguous cases where rule-based parsers fail.

Yes, if you need to parse unstructured US addresses at scale. The library is mature, permissively licensed, has low install friction, and sees heavy real-world use. The aging maintenance status (372 days since last release) is not a blocker—the repo is active and the model is stable—but be aware that accuracy is probabilistic, not perfect, and you should test on your own address patterns before relying on it in production.

Install

usaddress on PyPI

pip install usaddress

uv add usaddress

poetry add usaddress

Installing usaddress

Before you install

Low install friction with a pure-Python wheel distribution. The package is aging (372 days since last release) but remains actively maintained with recent commits; it has accumulated 1633 stars and sees substantial real-world use (5.2M monthly downloads).

License in practice

Released under the MIT License (permissive), so you can use, modify, and distribute usaddress freely in both open-source and commercial projects with minimal restrictions.

Quickstart

pip install usaddress

import usaddress
addr = '123 Main St. Suite 100 Chicago, IL'
usaddress.parse(addr)  # Returns list of (component, label) tuples
usaddress.tag(addr)    # Returns OrderedDict of labels and address type

Requires Python 3.9 or later.

Verify before relying

• Accuracy rates and typical error patterns on real-world address datasets remain undocumented in the fact sheet.
• Performance characteristics (latency, throughput) for batch address parsing are not specified.
• Whether the pre-trained model is regularly updated or retraining is required for new address patterns.

Package facts

Evidence: usaddress-0.5.16-py3-none-any.whl

Tags

More Scientific/Engineering packages