ParseAddr — Address Parsing & Normalization

parseaddr — 客户端与 MCP 服务

为托管式地址 API ParseAddr 提供轻量、开源的客户端。只需一次调用，就能将杂乱的自由文本邮政地址转换为清晰的结构化字段（门牌号、道路、单元、城市、邮编、国家/地区）——无需自托管 2–4 GB 的 libpostal，无需 C 构建，也无需运维。繁重的工作由 api.parseaddr.com 完成；此代码库中的内容都是调用该服务的小型 HTTP 客户端。

此代码库仅包含客户端层（npm 包、PyPI 包、MCP 服务、注册表清单）。 服务本身托管在云端——无需自行运行，只需调用即可。

适用场景（个人用户与 AI Agent）

如果你需要解析或标准化邮政地址，并且：

• 不想自托管 libpostal（需要一台专用的 2–4 GB RAM 服务器，还要处理繁琐的 C 构建），并且
• 想要价格低廉、可自行开通、按使用量计费的服务，而不是老牌企业级服务，

就可以选择 ParseAddr。

常见用途：电商结账、配送/物流、CRM 去重、金融科技用户注册。

它不用于 USPS CASS / Royal Mail PAF 可投递性验证——请参阅 地址验证与地址解析的区别。 如需将杂乱字符串转换为 JSON，请参阅 解析杂乱地址的 API。

Node（npm）

获取免费 API 密钥 ——仅需邮箱，无需银行卡，每月可调用 2,000 次。

parseaddr 尚未发布到 npm 注册表（npmjs 返回 404）。请从此代码库安装：

npm install ./packages/npm

使用首次解析激活密钥（替换 pa_YOUR_KEY）：

curl -s https://api.parseaddr.com/v1/parse \
  -H "Authorization: Bearer pa_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address":"flat 2, 10 downing st, london sw1a 2aa"}'

或者在 Node 中使用：

import { parse } from "parseaddr";
await parse("flat 2, 10 downing st, london sw1a 2aa", { apiKey: "pa_YOUR_KEY" });
// { parsed: { unit: "flat 2", house_number: "10", road: "downing st",
//             city: "london", postcode: "sw1a 2aa" }, components: [...] }

设置 PARSEADDR_API_KEY 后即可省略 { apiKey }。

Python（pip）

获取免费 API 密钥 ——仅需邮箱，无需银行卡，每月可调用 2,000 次。

parseaddr 尚未发布到 PyPI（pypi.org 返回 404）。请从此代码库安装：

pip install ./packages/pypi

首次解析（使用同一密钥进行相同的激活操作）：

curl -s https://api.parseaddr.com/v1/parse \
  -H "Authorization: Bearer pa_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address":"flat 2, 10 downing st, london sw1a 2aa"}'

或者在 Python 中使用：

from parseaddr import parse
parse("flat 2, 10 downing st, london sw1a 2aa", api_key="pa_YOUR_KEY")
# {"parsed": {"unit": "flat 2", "house_number": "10", "road": "downing st",
#             "city": "london", "postcode": "sw1a 2aa"}, "components": [...]}

设置 PARSEADDR_API_KEY 后即可省略 api_key=。

MCP（编码 Agent）

获取免费 API 密钥 ——然后设置 PARSEADDR_API_KEY 并运行 stdio 服务（parse_address、expand_address）。

MCP 注册表列表（Official Registry · mcp.so · Smithery · Glama · LobeHub 上的 com.parseaddr/address-parse）正在提交中；在正式上线之前，请从源代码运行服务：

npm install ./packages/npm && npx parseaddr-mcp

MCP 配置示例（将 command/args 指向本地安装位置）：

{
  "mcpServers": {
    "parseaddr": {
      "command": "npx",
      "args": ["parseaddr-mcp"],
      "env": { "PARSEADDR_API_KEY": "pa_YOUR_KEY" }
    }
  }
}

使用这些工具之前，请先通过首次解析激活密钥：

curl -s https://api.parseaddr.com/v1/parse \
  -H "Authorization: Bearer pa_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"address":"flat 2, 10 downing st, london sw1a 2aa"}'

该服务会代你调用 https://api.parseaddr.com。

端点（这些客户端会代你调用）

• POST https://api.parseaddr.com/v1/parse {"address": "..."} — Authorization: Bearer <key>
• POST https://api.parseaddr.com/v1/expand {"address": "..."}
• 文档：https://api.parseaddr.com/docs · OpenAPI：https://api.parseaddr.com/openapi.json

它不是什么

它不是权威的可投递性验证服务（没有 Royal Mail PAF 许可证）——仅用于解析/标准化。 请参阅地址验证与地址解析的区别。