从自然语言到四级行政区划：京东地址解析 API 最小可运行指南

适用场景在日常开发中从用户填写的文本地址中提取标准化的省、市、区、镇信息是一个常见的需求。例如电商平台的订单地址清洗、物流分单系统、CRM 中客户地址归一化、地图可视化的数据预处理等。传统行政区划接口通常只支持省、市、区三级而京东地址解析4 级接口额外提供了「镇街道」级别这使得对乡镇级地址的识别更加精准适合需要详细分拣的场景。接口能力边界在接入之前先了解该接口的关键限制解析深度返回数据包含省、市、区、镇四级以及每级对应的京东内部 ID。地址长度限制单个请求中的address字段不得超过 200 字符超出部分会被截断或导致解析错误。QPS 限制5 次/秒超过时服务器会返回 429 状态码需要配合退避重试。鉴权方式通过 HTTP HeaderAuthorization传递 API Key具体值需要从平台获取。请求方法仅支持 POST请求体为 JSON 格式。请求鉴参与参数Header 参数参数名是否必填类型说明Authorization是string你的 API Key通常格式为Bearer xxx或直接使用密钥字符串以平台文档为准Content-Type是string固定为application/json请求体参数参数名类型是否必填说明addressstring是待解析的自然语言地址文本最长 200 字符。示例北京市朝阳区三里屯街道工体北路 8 号请求体为单个 JSON 对象键名严格区分大小写。最小可运行示例curl以下是一个完整的 curl 命令你只需将YOUR_API_KEY替换为真实的密钥即可直接运行curl -sS \ -X POST \ -H Authorization: YOUR_API_KEY \ -H Content-Type: application/json \ -d {address: 北京市朝阳区三里屯街道工体北路 8 号} \ https://v1.apizero.cn/api/jd-address说明-sS表示静默模式但显示错误便于调试。如果使用 API Key 的格式为Bearer xxxxx则 Header 写为-H Authorization: Bearer xxxxx。返回结果将以 JSON 格式输出到终端。代码接入Python 最小示例为了更方便集成到工程中这里给出一个使用requests库的 Python 脚本同样保持最小可运行import requests import json API_URL https://v1.apizero.cn/api/jd-address API_KEY YOUR_API_KEY # 请替换为真实密钥 def parse_address(address_text): headers { Authorization: API_KEY, Content-Type: application/json } payload {address: address_text} resp requests.post(API_URL, headersheaders, jsonpayload) resp.raise_for_status() # 检查 HTTP 状态码 return resp.json() if __name__ __main__: addr 北京市朝阳区三里屯街道工体北路 8 号 result parse_address(addr) print(json.dumps(result, indent2, ensure_asciiFalse))运行脚本将输出解析后的结构化数据。注意代码中jsonpayload会自动设置正确的 Content-Type。返回值解读成功时 HTTP 状态码为 200响应体 JSON 示例{ code: 0, data: { province: 北京, province_id: 1, city: 北京市, city_id: 72, county: 朝阳区, county_id: 2818, town: 三里屯街道, town_id: 53124, detail: 工体北路 8 号 }, msg: 成功 }字段说明字段类型说明codeint业务状态码0 表示成功非 0 表示失败msgstring状态描述信息data.provincestring省/直辖市名称如北京data.province_idint京东内部的省 IDdata.citystring市/直辖市名称如北京市data.city_idint京东内部的市 IDdata.countystring区/县名称如朝阳区data.county_idint京东内部的区县 IDdata.townstring镇/街道名称如三里屯街道data.town_idint京东内部的镇 IDdata.detailstring地址中除去四级行政区划后的剩余详细地址注意某些地址可能解析不出镇级信息此时town和town_id可能为空或返回默认值。常见错误处理HTTP 状态码可能原因处理建议401 / 403API Key 无效、未携带或已过期检查 Authorization Header 是否正确确认密钥是否有效400请求体格式错误如address字段缺失、超过 200 字符、JSON 语法错误确认请求体为合法 JSON且address值不为空且长度合规429请求频率超过 QPS 限制5次/秒实现指数退避重试或在短时间窗口内控制请求间隔500服务器内部错误稍后重试若持续出现则联系技术支持业务状态码code非 0 时可结合msg字段判断具体问题。例如code: 1001可能表示地址无法识别需要检查地址格式是否合理。工程化注意事项密钥管理不要将 API Key 硬编码在代码仓库中应通过环境变量或配置管理工具加载。并发控制当需要批量解析地址时建议使用队列限速将请求间隔控制在 200ms 以上避免触发 429。地址预处理用户输入的地址可能包含特殊字符、多余空格或标点。调用前建议做简单的清洗如去除首尾空格、将全角符号转为半角以提高解析成功率。缓存策略对于重复出现的地址如常用收件地址可缓存其解析结果以减少 API 调用量。错误重试对于 5xx 和 429 错误使用指数退避重试初始等待1秒最大等待30秒。4xx 错误通常不需要重试应检查请求参数。参考文档京东地址解析4级API 官方文档https://apizero.cn/aidocs/jd-address原始 Markdown 文档https://apizero.cn/aidocs/jd-address/raw.md以上文档包含更详细的字段说明和更新日志建议结合实际业务查阅。