指南

为结账表单添加地址自动补全

结账表单在地址字段上出错的频率高于其他任何字段,通常是因为客户输错了街道名称或漏填了单元号。在客户输入时推荐真实地址,可以在大多数问题演变成配送失败之前就将其解决。

自动补全请求

/v1/autocomplete 端点接收部分文本以及返回建议数量的上限。在客户输入了几个字符后,随着输入调用它。

GET /v1/autocomplete?q=221B Baker&limit=5
{
  "status": "ok",
  "query": "221B Baker",
  "suggestions": [
    {"text": "221B Baker Street, London, UK", "place_id": "abc123"},
    {"text": "221B Baker Avenue, Springfield", "place_id": "abc124"}
  ]
}

从建议到完整地址

一条建议只是一个简短的标签和一个 place_id,而不是完整的地址记录。客户选定一条后,将建议文本传给 /v1/forward,把它解析为带有地址组成部分和坐标的完整地址。正是这第二次调用填充了表单上的街道、城市、地区和邮政编码字段。

GET /v1/forward?q=221B Baker Street, London, UK&limit=1

components 对象实际上只出现在第二次请求中,因为 /v1/autocomplete 只返回文本标签和 place_id,从不返回街道、城市和邮政编码的拆分。跳过这一步、自己去解析建议文本,比看上去要脆弱得多,因为地址格式因国家而异。

控制请求数量

在繁忙的结账页面上,每次按键都发送请求,请求数会迅速累积。请对字段做防抖处理,只在客户停顿片刻后才发出请求,并跳过少于三四个字符的输入,反正这时的建议也没什么用。每次自动补全调用和随后的每次正向地理编码调用都按一次请求计入您的每日配额,因此即使是繁忙商店上做了防抖的字段,也能轻松控制在每个密钥附带的每天 2,500 次免费请求之内。

处理无匹配结果

空的 suggestions 数组是正常响应,而不是错误。让客户继续输入,如果输入几个字符后仍没有有用的结果,就退回到普通文本地址字段,而不是在客户选中建议之前阻止表单提交。

值得避免的错误

把点击过的建议当作已完成、已验证的地址,是一种常见但日后会出问题的捷径。客户可能选中一条建议后又继续编辑该字段,修改门牌号或加上原建议中没有的公寓号。请始终在提交时通过 /v1/forward 解析字段的最终文本,而不仅仅在点击建议的那一刻解析,这样您保存的地址才能反映字段中最终实际填写的内容。

如果您的结账表单还单独收集邮政编码,那么在街道地址解析完成后调用一次 /v1/postcode,就能以很低的成本发现与地址其余部分不符的邮政编码,避免两者一起提交后在后续环节造成配送信息不一致。

自动补全不能取代验证,它只是降低了错误地址一开始就进入您订单系统的几率。在将其接入结账流程之前,请参阅地址自动补全文档了解完整的参数列表。