My Geocode

指南

为配送表单添加邮政编码自动填充

· 阅读约 4 分钟 · My Geocode · #postal-code#forms#shipping#autofill

为邮政编码、城市和地区分别设置字段的收货表单，要求客户输入的信息往往仅凭一个邮政编码就已经能推断出来。

查询邮政编码

客户输入完邮政编码并选择国家后，或者如果已从其账户得知国家，就将两者一起发送到 /v1/postcode。

GET /v1/postcode?code=SW1A 1AA&country=GB
{
  "status": "ok",
  "postcode": "SW1A 1AA",
  "country_code": "GB",
  "results": [
    {"lat": 51.5014, "lon": -0.1419, "components": {"city": "London", "region": "Greater London", "country": "GB"}}
  ]
}

填充表单字段

直接用结果中 components 对象的内容填充城市和地区字段，并让客户确认或更正，而不是完全锁定这些字段，因为邮政编码偶尔会跨越边界，或覆盖不止一个常用地名。

第二个示例：为计税预填账单地区

同样的查询也适用于需要客户所在地区来计税的注册或账单表单，而不仅仅是收货表单。在输入账单邮政编码后触发同样的邮政编码查询，就能使用完全相同的请求和响应结构，在两种场景中一致地填充地区字段，因此同一套客户端和服务器端处理代码可以同时服务于两个表单。

在正确的时机触发查询

请在邮政编码字段失去焦点时，或者在其达到所选国家的预期长度时再执行查询，而不是每次按键都查询，因为邮政编码只有在完整时才值得查询。这样该功能每次完成字段输入只需一次请求，而不是每输入一个字符就请求一次。

需要避免的常见错误

不要为所有国家的邮政编码格式硬编码一个固定的预期长度。适用于某个国家的五位数假设，对于使用不同长度或像上例那样采用字母数字格式的国家，要么会过早触发查询，要么永远不会触发。要么不论长度都在失去焦点时触发，要么维护一张小型的按国家长度表，以便对您最常支持的国家提前触发。

处理无法识别的邮政编码

空的 results 数组表示该邮政编码在该国家无法识别，最常见的原因是输入错误。请将城市和地区字段留空，让客户手动填写，而不是阻止表单提交，因为仅因自动填充失败就直接拒绝该字段，体验远不如在这种情况下简单地请客户手动输入。

一个边界情况：一个邮政编码对应多个地名

有些邮政编码覆盖的区域在当地确实有不止一个地名，或者恰好位于两个常用城市名称的交界处。遇到这种情况时，把返回的值显示为可编辑的建议而不是固定标签，客户就能将其改成自己实际使用的名称，而不会把其中任何一个视为比另一个更官方或更不官方。

地址完整后获取精确坐标

根据邮政编码自动填充得到的是区域级位置，足以填写城市和地区字段；但一旦客户在此基础上输入了完整的街道地址，再通过 /v1/forward 处理完整地址，就能获得运单或配送路线系统真正需要的精确坐标。

成本是多少

每填完一个邮政编码字段就触发一次请求。即使收货表单每天处理大量订单，该功能的使用量也不大，每个订单一次查询而不是每次按键一次，对大多数商店来说都远在每个密钥附带的每天 2,500 次免费请求之内。

对于绝大多数输入有效邮政编码的客户，根据邮政编码自动填充城市和地区，可以让收货表单少填两个字段。完整的字段定义请参阅邮政编码查询文档。

更多指南

· 阅读约 4 分钟

将地址与其邮政编码交叉核对

分别解析街道地址和邮政编码，并比较它们实际指向的位置，在订单发货前发现两者不匹配的情况。