适用场景京东地址解析4级API 主要用于将自然语言描述的中文地址拆解为“省、市、区、镇”四级行政区划并返回每一级对应的京东内置 ID。典型的应用场景包括电商收货地址标准化用户下单时输入的自由文本地址通过此接口转换为结构化数据便于仓储、配送系统识别。物流分拣与路由四级镇级信息可细化到街道/乡镇提升末端分拣准确率。地址清洗与补全清洗历史订单地址数据统一格式支撑数据分析或地图可视化。政务/社区数据对接涉及社区居民管理的业务需要精确到镇/街道级别。接口能力边界属性说明接口名称京东地址解析4级请求方法POST请求地址https://v1.apizero.cn/api/jd-address输入限制address 字段 ≤ 200 字符支持中文、英文、数字及常见标点输出精度省、市、区、镇四级 详细地址detail并发限制5 QPS超出会返回限流错误数据来源京东地址库镇级 ID 为京东自有编码注意接口仅返回匹配到的行政区划若地址中的镇级信息无法识别town和town_id可能为空字符串或 null具体以实际响应为准。参数与鉴权详解Header 参数参数类型必填说明Authorizationstring是API 密钥通常格式为Bearer YOUR_API_KEY。实际调用中以文档提供的字段名为准示例中使用X-API-Key。Content-Typestring是固定值application/json鉴权方式请严格参照原始文档 https://apizero.cn/aidocs/jd-address/raw.md 中的说明不同子账号可能使用不同的 Header 名称。请求体Body字段类型必填说明addressstring是待解析的地址文本最长 200 字符。无需前置清洗但建议去除多余换行和 HTML 标签。请求体示例JSON{ address: 北京市朝阳区三里屯街道工体北路 8 号 }接入示例cURL 与代码片段cURL 示例可直接复制运行curl -sS \ -X POST \ -H X-API-Key: YOUR_API_KEY \ -H Content-Type: application/json \ -d {address: 北京市朝阳区三里屯街道工体北路 8 号} \ https://v1.apizero.cn/api/jd-address请将YOUR_API_KEY替换为实际有效的 API 密钥。接口返回纯 JSON可配合jq工具解析。Python 请求示例import requests url https://v1.apizero.cn/api/jd-address headers { X-API-Key: YOUR_API_KEY, Content-Type: application/json } payload {address: 广东省深圳市南山区粤海街道科技南路 18 号} resp requests.post(url, jsonpayload, headersheaders) data resp.json() print(data)Node.js 示例const axios require(axios); const url https://v1.apizero.cn/api/jd-address; const headers { X-API-Key: YOUR_API_KEY, Content-Type: application/json }; const payload { address: 浙江省杭州市西湖区转塘街道之江路 188 号 }; axios.post(url, payload, { headers }) .then(response console.log(response.data)) .catch(error console.error(error));返回值解读成功响应HTTP 200{ code: 0, msg: 成功, data: { province: 北京, province_id: 1, city: 北京市, city_id: 72, county: 朝阳区, county_id: 2818, town: 三里屯街道, town_id: 53124, detail: 工体北路 8 号 } }字段说明字段类型说明codeint业务状态码0 表示成功非 0 表示异常msgstring状态描述成功为“成功”失败时给出具体原因data.provincestring省/直辖市/自治区名称如“北京”、“广东”data.province_idint京东内置的省级 IDdata.citystring地级市名称如“北京市”、“深圳市”data.city_idint京东内置的地市级 IDdata.countystring区/县名称如“朝阳区”、“南山区”data.county_idint京东内置的区县级 IDdata.townstring镇/街道名称如“三里屯街道”。若无法识别则为空字符串data.town_idint京东内置的镇级 ID。若无法识别则可能为 0 或 nulldata.detailstring地址中去除行政区划后的剩余部分门牌号、小区名等注意town字段是此接口区别于传统三级地址接口的核心特性。当输入的地址不含镇/街道信息时town和town_id可能为空。错误响应示例{ code: 10001, msg: 参数错误address 不能为空, data: null }常见错误与排查错误现象可能原因解决方法HTTP 401缺少 Authorization 或 Key 无效检查 Header 中X-API-Key或Authorization是否正确从控制台重新创建密钥HTTP 400请求体不是合法 JSON 或缺少 address 字段确保 Content-Type 为application/jsonbody 为 JSON 对象且包含addresscode: 10001address 为空字符串或超过 200 字符检查输入长度去除前后空白code: 10002地址解析失败无法匹配任何省市区镇可能是地址过于模糊或用词不规范如“帝都”建议使用更标准的地址描述限流错误HTTP 429请求频率超过 5 QPS增加本地延迟或使用请求队列加入指数退避重试逻辑town返回空输入地址中未包含镇/街道信息或京东库中无此记录这属于正常情况业务逻辑需兼容空 town 场景工程化注意事项1. 地址预处理虽然接口支持原始自然语言但提前做轻量清洗能提高解析成功率删除地址中的 HTML 标签、多余空格、换行符。统一全角/半角字符如将全角数字转半角。对于非常规地址如“东门老街3号”建议补充区划前缀。2. 限流与重试接口 QPS 上限为 5即每秒钟最多发送 5 个请求。若计划批量处理大量地址必须控制速率。可维护一个令牌桶或固定间隔发送。推荐重试策略当收到 HTTP 429 或网络超时时采用指数退避如等待 1s、2s、4s… 最多 3 次。3. 缓存策略对于同一地址的重复解析例如固定收货地址建议在业务侧建立本地缓存如 Redis设置 TTL 为 1 天避免重复请求浪费配额。缓存 key 可使用地址原文的 MD5 或 SHA256 值。4. 多级地址的补全与容错部分用户地址可能只写到区级例如“北京市朝阳区”此时 town 字段为空。业务系统应能正常处理缺少镇级信息的情况例如在配送流程中回退到区级。如果解析出的省市区与实际业务预期不符建议增加人工复核环节或记录异常日志。5. 安全与密钥管理API 密钥切勿硬编码在代码仓库中。推荐使用环境变量或密钥管理服务如 AWS Secrets Manager、Vault。定期轮换密钥并设置 IP 白名单如果平台支持。6. 响应校验解析后应验证data.province,data.city,data.county是否为空。即使 code 为 0data 中也可能出现部分字段缺失例如输入地址为“随便”时。建议将detail字段与原始地址拼接作为兜底地址以防解析不完整。参考文档官方文档页https://apizero.cn/aidocs/jd-address原始接口定义Markdownhttps://apizero.cn/aidocs/jd-address/raw.md