指南

在保存邮政编码之前先进行验证

一个只检查长度和字符格式的邮政编码字段,会欣然接受一个格式完美却完全错误的编码。真正的验证意味着检查该编码能否解析到一个真实的地点。

验证调用

将邮政编码和该国家的 ISO 3166-1 alpha-2 代码传给 /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"}}
  ]
}

将空结果视为无效

如果 results 返回为空,说明该邮政编码与国家的组合不对应任何已知位置。这就是您应当以清晰的提示信息拒绝该表单字段的信号,而不是让一个虚构的编码溜过去,日后出现在运单标签上。

验证不等于精确的地址匹配

一个邮政编码覆盖的是一片区域,因国家而异,有时很小,有时很大,因此验证通过只能确认该编码存在,而不能确认它与表单上同时填写的具体街道地址相符。当您需要邮政编码和街道两者一致时,请将邮政编码验证与针对完整地址的正向地理编码检查结合使用。

值得避免的错误

在还没把编码发送给 API 之前,就纯粹因为它不符合您自己的格式预期而拒绝它,会因为一个表面上的差异而丢弃有效的输入。一个少打了空格、多了空格或大小写不一致的编码,在规范化之后往往仍然是有效的邮政编码。请在调用 /v1/postcode 之前,先对字段中的空白和大小写进行修剪和规范化,而不是因为查询本身完全可以容忍的格式小问题就直接拒绝该输入。

一个边缘情况:编码正确,国家错误

一个语法上有效的邮政编码,仍可能仅仅因为同时选错了国家而无法通过验证,因为同一种数字或字母数字格式可能在多个国家的编码体系中都是有效编码。如果客户坚称某个编码正确,查询却返回空结果,请先确认国家字段与客户的实际意图一致,再把问题归咎于邮政编码本身。

在哪里运行这项检查

请在字段失去焦点或提交表单时运行检查,而不是在每次按键时运行,因为邮政编码通常要完整输入后才有验证的意义。这样每次提交尝试只需一次请求,而不是每输入一个字符就发一次请求。

在所有地方都这样做的成本

每次表单提交调用一次验证,就是一次请求。即使是流量很大的表单,仅用于邮政编码验证,也只会用掉每个密钥附带的(或单个地址无需密钥即可使用的)每天 2,500 次免费请求中的一小部分。

在错误的邮政编码进入运单之前把它拦下来,值得多花这一次请求。完整的参数说明见邮政编码查询文档