跳到主要内容

3. 地址解析

把一行自由文本、一个地图链接或一对经纬度,变成结构化地址 + 坐标。

这个接口不受套餐限制,但仍需鉴权(签名或会话,见组织鉴权)。两个场景都会用到:

  1. 建单前 —— 规范化收件地址,拿到标准的省/市/区/邮编再填进运单
  2. 报价前 —— 拿到经纬度。报价接口强制要求坐标且永不代你做地理编码,详见配送规划与跟踪

解析地址​

POST /api/address/resolve

三种输入模式三选一,返回结构完全相同:

模式字段说明
自由文本address (string)最常用
地图链接url (string)Google Maps 分享链接或短链
反查lat + lng (number)已有坐标,反查结构化地址

url 只接受 Google Maps 链接,其他链接直接返回 400,不会被访问。认可的形式:

  • maps.app.goo.gl/…、goo.gl/maps/… 短链
  • maps.google.<域名后缀>/…
  • www.google.<域名后缀>/maps/…、google.<域名后缀>/maps/…

<域名后缀> 可以是 com、两位国家后缀(如 de),或 co.xx、com.xx 形式(如 co.th、com.hk)。http:// 链接按 https:// 处理;带端口号或用户名密码的链接不接受。

短链的跳转只在上述地址之间跟随,最多 5 次。跳到其他页面(例如部分地区先跳到的 Google 同意页)时解析不出坐标,返回 404;这时改传链接里的经纬度,或直接传地址文本。

可选字段:

字段类型说明
countrystringISO-2 国家码,如 TH、VN。强烈建议传 —— 它会影响地理编码的区域和语言偏好
logResolutionboolean是否记录本次解析,默认 true

请求示例​

{
"api_key": "ak_example000000",
"nonceStr": "1771545600000",
"sign": "...",
"address": "123 Sukhumvit Rd, Bangkok",
"country": "TH"
}

响应​

{
"lat": 13.7563,
"lng": 100.5018,
"country": "TH",
"province": "กรุงเทพมหานคร",
"district": "เขตปทุมวัน",
"subdistrict": "แขวงปทุมวัน",
"postal_code": "10330",
"formatted_address": "ถนน พระรามที่ 1 แขวงปทุมวัน เขตปทุมวัน กรุงเทพมหานคร 10330 ไทย",
"place_name": null,
"confidence": 0.95,
"source": "google_geocoding"
}
字段说明
confidence0–1 的匹配可信度
source命中的数据源:google_geocoding、google_places、postal_centroid、province_centroid
place_name地点名称,只有 source 为 google_places(按地标/商场等检索命中)时才有值,其余为 null

:::note 返回的是当地语言 省/区/街道等行政区名称和 formatted_address 按 country 对应的当地语言返回:TH 返回泰文,VN 返回越南文,CN 返回中文,其他国家返回英文;不传 country 时按泰国处理。请求里写英文地址也一样。例外是两种中心点兜底结果(postal_centroid、province_centroid):它们的 province 一般是英文省名。 :::

务必判断 confidence​

:::danger 解析器总会返回点什么 这个接口采用逐级兜底策略:精确地理编码 → 地点检索 → 仅按行政区匹配 → 邮编中心点 → 省中心点。最后一级的 confidence 只有 0.32,坐标落在省会城市中心,和真实地址可能差上百公里。

所以只要能匹配到邮编或省份,它就会返回结果 —— 判断"这个结果能不能用"的责任在你这边。 :::

:::note 404 也是正常结果 以下情况会返回 404,请当作"解析不到"处理,而不是系统故障:

  • 自由文本:地理编码和地点检索都没有足够可信(confidence ≥ 0.68)的结果,文本里也识别不出可用的邮编或省份
  • 地图链接:链接里取不到坐标,或坐标反查不到地址
  • 经纬度:该坐标反查不到地址 :::

建议的处理策略:

confidence建议
≥ 0.68可直接使用
< 0.68视为不可靠,转人工确认或要求客户补充地址

同时看 source:命中 province_centroid 或 postal_centroid 说明只匹配到了行政区,没匹配到门牌,用于报价会导致算错行程和价格。

const from = await resolve({ address: userInput, country: 'TH' });
if (from.confidence < 0.68 || from.source === 'province_centroid') {
throw new Error('地址太模糊,无法定价,请让客户补充详细地址');
}

错误​

HTTP说明
400三种输入模式一个都没给,经纬度超出范围(纬度 ±90、经度 ±180),或 url 不是 Google Maps 链接(见上文“地图链接”的认可形式,返回 { "error": "url must be a Google Maps link" })
401签名缺失或无效,见鉴权排查
404解析不出任何结果,见上文
500地理编码服务暂时出错,可稍后重试

行政区查询​

需要做省/市/区三级联动下拉,或校验用户填的行政区是否存在:

GET /api/regions?country=TH
GET /api/regions?country=TH&postal_code=10330

country 必填,否则返回 400。它按大写 ISO-2 国家码精确匹配:th 或不支持的国家不会报错,而是返回空列表 {"provinces": []}。传 postal_code 时只返回该邮编下的行政区。

返回三级嵌套结构(直接是这个对象,没有 data 包裹):

{
"provinces": [
{
"name": "กรุงเทพมหานคร",
"cities": [
{ "name": "เขต ปทุมวัน", "districts": [{ "name": "ปทุมวัน", "code": "10330" }] }
]
}
]
}

注意键名和实际层级的对应关系:

键实际层级
provinces[]省
provinces[].cities[]区/县(泰国的 อำเภอ / เขต)
provinces[].cities[].districts[]街道/乡(泰国的 ตำบล / แขวง)
districts[].code该街道的邮编,不是行政区划代码。多个街道可能共用一个邮编

名称都是当地语言(泰国为泰文)。

查询支持的国家列表:

GET /api/regions/countries

返回有行政区数据的国家码列表:

{ "data": ["TH", "VN"] }

这两个接口同样不受套餐限制,但同样需要鉴权,未通过返回 401。