usaddress

usaddress 是一个 Python 库，用于使用先进的自然语言处理（NLP, Natural Language Processing）方法，将非结构化的美国地址字符串解析为地址组成部分。

它能做什么： 使用概率模型，即使在规则型解析器通常失效的复杂情况下，也能对地址组件进行（非常有根据的）猜测识别。

它不能做什么： 它无法以完美准确度识别地址组件，也无法验证给定地址是否正确或有效。

它也不会对地址进行标准化。不过，这个基于 usaddress 构建的库可以。

基于 usaddress 构建的工具

Parserator API

这是一个构建在 usaddress 之上的 RESTful API，专为不使用 Python 的程序员设计。需要 API 密钥，前 1,000 次解析免费。

Parserator Google Sheets 应用

Parserator: Parse and Split Addresses 允许你在 Google Sheets 中轻松将地址按街道、城市、州、邮政编码等拆分为独立列。

如何使用 usaddress Python 库

1. 使用 pip（一个用于安装和管理 Python 包的工具）安装 usaddress。（新手指南在此）

在终端中运行：

pip install usaddress

2. 解析一些地址！

注意 parse 和 tag 是不同的方法：

import usaddress
addr='123 Main St. Suite 100 Chicago, IL'

# parse 方法会将你的地址字符串拆分为组件，并为每个组件打标签。
# 预期输出：[(u'123', 'AddressNumber'), (u'Main', 'StreetName'), (u'St.', 'StreetNamePostType'), (u'Suite', 'OccupancyType'), (u'100', 'OccupancyIdentifier'), (u'Chicago,', 'PlaceName'), (u'IL', 'StateName')]
usaddress.parse(addr)

# tag 方法会更智能一些
# 它会合并连续的组件、去除逗号，并返回地址类型
# 预期输出：(OrderedDict([('AddressNumber', u'123'), ('StreetName', u'Main'), ('StreetNamePostType', u'St.'), ('OccupancyType', u'Suite'), ('OccupancyIdentifier', u'100'), ('PlaceName', u'Chicago'), ('StateName', u'IL')]), 'Street Address')
usaddress.tag(addr)

如何使用此开发代码（面向极客）

usaddress 使用 parserator，这是一个用于创建和改进概率解析器的库——特别是使用 python-crfsuite 实现的条件随机场（Conditional Random Fields）的解析器。Parserator 允许你在标注的训练数据上训练 usaddress 解析器的模型（一个 .crfsuite 配置文件），并提供添加新标注训练数据的工具。

构建与测试本仓库中的代码

要在你的机器上构建 usaddress 的开发版本，请在命令行中运行以下代码：

git clone https://github.com/datamade/usaddress.git  
cd usaddress  
pip install -e ."[dev]"

然后运行测试套件，确认一切正常工作：

pytest

构建代码遇到问题？提交一个 issue，我们很乐意帮你排查。

添加新的训练数据

如果 usaddress 在某些特定地址模式上持续失败，你可以通过向模型添加新的训练数据来调整解析器的行为。请遵循 training 目录中的指南，并务必提交 pull request，以便我们将你的贡献纳入下一个版本！

重要链接

• 网页界面：https://parserator.datamade.us/usaddress
• Python 包分发页面：https://pypi.python.org/pypi/usaddress
• Python 包文档：https://usaddress.readthedocs.io/
• API 文档：https://parserator.datamade.us/api-docs
• 代码仓库：https://github.com/datamade/usaddress
• 问题追踪：https://github.com/datamade/usaddress/issues
• 博客文章：http://datamade.us/blog/parsing-addresses-with-usaddress

团队

• Forest Gregg，DataMade
• Cathy Deng，DataMade
• Miroslav Batchkarov，萨塞克斯大学
• Jean Cochrane，DataMade

错误解析 / Bug

请在 issue tracker 中报告问题。

如果某个地址被错误解析，请告诉我们！你可以提交一个 issue，或者（如果你喜欢挑战）添加新的训练数据以改进解析器模型。如有可能，请提供几个类似地址模式的真实示例及数据来源信息——这将帮助我们训练解析器并提升其性能。

如果库中的某些行为不符合直觉，那就是一个 bug，应当报告。

关于补丁/Pull Requests 的说明

• Fork 本项目。
• 添加你的功能或修复 bug。
• 向我们发送 pull request。使用主题分支会有额外加分！

版权

版权所有 (c) 2025 Atlanta Journal Constitution。依据 MIT 许可证 发布。

usaddress 快速上手指南

环境准备

• 系统要求：支持 Python 3.6 及以上版本的操作系统（Windows/macOS/Linux 均可）
• 前置依赖：确保已安装 pip，推荐使用虚拟环境管理项目依赖
• （可选）国内用户建议配置 pip 阿里云镜像加速：

  pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
  

安装步骤

在终端中执行以下命令安装：

pip install usaddress

如需开发版本或参与贡献，可从源码安装：

git clone https://github.com/datamade/usaddress.git  
cd usaddress  
pip install -e ."[dev]"

基本使用

安装完成后，在 Python 脚本或交互环境中导入并解析地址：

import usaddress

addr = '123 Main St. Suite 100 Chicago, IL'

# 方法一：parse —— 拆分并标注每个组件
usaddress.parse(addr)
# 输出示例: [(u'123', 'AddressNumber'), (u'Main', 'StreetName'), ...]

# 方法二：tag —— 智能合并组件并返回地址类型
usaddress.tag(addr)
# 输出示例: (OrderedDict([...]), 'Street Address')

⚠️ 注意：parse() 返回元组列表，tag() 返回结构化字典 + 地址类型，按需选择。