拇指云（厦门）软件有限公司

地址标准化解析

接口编号 ADDR001 · 开放平台开发文档

地址标准化解析

接口编号ADDR001分类知识产权服务 / 作品著作权状态启用

1、接口说明

地址标准化解析接口，接收原始地址文本，自动完成地址结构化解析，输出【省、市、区县、乡镇街道、行政区划编码】等结构化字段，回传原始输入文本，对用户填报的非标准化地址进行结构化拆分。

2、接口信息

请求地址	`https://quanzhou.muzhiyun.com/api/addr.do`
请求方式	POST
请求格式	`application/json; charset=utf-8`
响应格式	`application/json; charset=utf-8`
超时时间	60 秒（建议）
计费方式	免费

本接口免费，调用不计费、不扣款。

3、鉴权说明

所有请求必须携带下列三个公共参数，缺一不可。它们既是请求参数，也参与签名。

参数名	说明	类型	必填	示例	备注
`appid`	应用ID	String(32)	是	`muzhiyun`	开放平台分配的应用标识，调用方身份凭证
`sendtime`	请求时间戳	Int	是	`1790784000`	Unix 时间戳（秒）；与服务器时间相差过大视为过期请求
`sign`	签名	String(32)	是	`BEE42F7A74F4482A9A405EDB229CFB6C`	签名值：参与签名的参数按变量名升序拼接后加密，不含本字段

签名算法

1) 取本次请求的全部参数（不含 sign 自身）；
2) 按参数名 ASCII 升序排序，拼接成 k1=v1&k2=v2&…；
3) 末尾追加 &key=你的AppKey；
4) 对整串做 MD5 后转大写，即得 sign。

调用示例 · 按本接口真实示例值实算一遍

你的 AppKey（仅本地签名用，不随请求发送）：YOUR_APP_KEY

参与签名的参数（已剔除 sign 自身，按参数名升序）

appid=muzhiyun&sendtime=1792521184&text=厦门市思明区厦禾路813-1号101室

末尾追加 &key=你的AppKey

appid=muzhiyun&sendtime=1792521184&text=厦门市思明区厦禾路813-1号101室&key=YOUR_APP_KEY

整串做 MD5 后转大写，得到 sign

9C24155139FCE6ECF7BA58835398C2A4

最终请求参数（JSON 包，作为请求 Body 发送）

{
    "appid": "muzhiyun",
    "sendtime": "1792521184",
    "text": "厦门市思明区厦禾路813-1号101室",
    "sign": "9C24155139FCE6ECF7BA58835398C2A4"
}

上例 AppKey 写作 YOUR_APP_KEY，请换成你自己的 AppKey 重算 sign —— sign 与 AppKey 绑定，同样的参数换 AppKey 会得到完全不同的 sign。复制本例后，把 YOUR_APP_KEY 替换为你自己的 AppKey，再按 ①②③ 重算 sign 即可直接调用（sendtime 为当前时间戳，300 秒内有效）。排序只按参数名，不看参数值；布尔值按 1/0 参与拼接；数组型参数不参与签名。

时间戳要求：sendtime 为 10 位 Unix 秒级时间戳，与服务器时间相差超过 300 秒 视为过期请求。AppID / AppKey 由开放平台发放，可在「用户管理 → 开发者凭证」中查看。

4、请求参数

以下参数通过 Body（application/json） 传递

参数名	说明	类型	必填	示例	备注
`text`	地址	Text	是	`厦门市思明区厦禾路813-1号101室`	—

5、返回结果

接口统一返回 JSON，ok=1 表示成功、ok=0 表示失败；鉴权或配置类错误同时返回 HTTP 666。

字段	类型	说明
`ok`	Int	1=成功，0=失败
`msg`	String	结果描述 / 失败原因

成功响应示例

{
    "ok": 1,
    "msg": "解析成功",
    "province": "福建",
    "city": "厦门市",
    "district": "思明区",
    "town": "开元街道",
    "address": "厦禾路813-1号101室",
    "provinceID": 409,
    "cityID": 453,
    "districtID": 460,
    "code": "350203",
    "text": "厦门市思明区厦禾路813-1号101室"
}

失败响应示例

{
    "ok": 0,
    "msg": "请传入地址",
    "text": ""
}

余额不足 / 无可用套餐

{
    "ok": 0,
    "msg": "余额不足，且无可用套餐，请充值后重试。"
}

接口已停用

{
    "ok": 0,
    "msg": "接口【地址标准化解析】已停用，暂停调用，请联系管理员。"
}

常见错误提示（msg 原文）

缺少必要的参数【appid、sendtime、sign】请详看开发文档。
AppID不存在，请联系产品经理进行业务开通。
sendtime不是10位的数字。
时间戳超时，请重新请求。
签名校验失败。
余额不足，请充值后重试。
接口【XXX】已停用，暂停调用，请联系管理员。

6、调用示例

下面示例自动计算签名（ksort 后 MD5 大写）：复制后只需把 你的AppID / 你的AppKey 换成真实凭证即可运行。Python / PHP 为完整可运行版；cURL、JavaScript 展示请求形态。GET 接口请把参数（含 appid/sendtime/sign）拼到 URL 查询串。

cURL

curl -X POST "https://quanzhou.muzhiyun.com/api/addr.do" \
  -H "Content-Type: application/json" \
  -d &#039;{"appid":"你的AppID", "sendtime":"<当前时间戳>", "sign":"<按签名算法计算>", "appid":"muzhiyun","sendtime":"1790784000","text":"厦门市思明区厦禾路813-1号101室" }'

PHP

<?php
$appId  = "你的AppID";      // 没有则填 muzhiyun
$appKey = "你的AppKey";
$url    = "https://quanzhou.muzhiyun.com/api/addr.do";

$params = [
    &#039;appid' => 'muzhiyun',
    &#039;sendtime' => '1790784000',
    &#039;text' => '厦门市思明区厦禾路813-1号101室',
];
// 以下三项由代码自动补，无需手填
$params["appid"]    = $appId;
$params["sendtime"] = (string)time();
ksort($params);
$src = &#039;';
foreach($params as $k=>$v) $src .= $k.&#039;='.$v.'&';
$src .= &#039;key='.$appKey;
$params["sign"] = strtoupper(md5($src));

$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL            => $url,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [&#039;Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode($params, JSON_UNESCAPED_UNICODE),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
]);

$resp = curl_exec($ch);
curl_close($ch);
echo $resp;

Python

import time, hashlib, json, urllib.request

APP_ID  = "你的AppID"      # 没有则填 muzhiyun
APP_KEY = "你的AppKey"
URL     = "https://quanzhou.muzhiyun.com/api/addr.do"

params = {
    "appid": "muzhiyun",
    "sendtime": "1790784000",
    "text": "厦门市思明区厦禾路813-1号101室",
}
params["appid"]    = APP_ID
params["sendtime"] = str(int(time.time()))
params = dict(sorted(params.items()))  # 参数名升序
sign_src = "&".join(f"{k}={v}" for k, v in params.items()) + "&key=" + APP_KEY
params["sign"] = hashlib.md5(sign_src.encode("utf-8")).hexdigest().upper()

req = urllib.request.Request(
    URL,
    data=json.dumps(params).encode("utf-8"),
    headers={"Content-Type": "application/json"},
    method="POST",
)
print(urllib.request.urlopen(req, timeout=30).read().decode("utf-8"))

JavaScript

const url = "https://quanzhou.muzhiyun.com/api/addr.do";
const params = {
  &#039;appid': 'muzhiyun',
  &#039;sendtime': '1790784000',
  &#039;text': '厦门市思明区厦禾路813-1号101室',
  appid: "你的AppID",
  sendtime: String(Math.floor(Date.now()/1000)),
  // sign: 按上文「签名算法」在前端算 md5(ksort(k=v&…)&key=AppKey) 后填入
};
fetch(url, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify(params),
}).then(r => r.json()).then(console.log);

7、注意事项

1、调用时请求参数text（待解析地址文本）不能为空，输入地址文本不要超过200字符，超长部分接口内部会自动截断。
2、返回结果中code为原始区县编码，provinceID、cityID、districtID 是福建省版权局的区划编码，开发可以无需关心，拇指云平台会自动解决。
3、解析结果存在识别失败场景，业务需要对ok=0的返回做好兼容。