结合邮政编码和国家实现更快的查询

正向地理编码是为处理杂乱的自由文本而设计的，这意味着它会在后台做一些工作来判断所面对的是哪种输入。如果您已经确定手头是干净的邮政编码和国家，那么还有一条更直接的途径。

直接使用邮政编码端点

不必拼接一个自由文本字符串再发送到 /v1/forward，而是直接把邮政编码和国家发送到 /v1/postcode。

GET /v1/postcode?code=90210&country=US

{
  "status": "ok",
  "postcode": "90210",
  "country_code": "US",
  "results": [
    {"lat": 34.0901, "lon": -118.4065, "components": {"city": "Beverly Hills", "region": "CA", "country": "US"}}
  ]
}

为什么这样更合适

邮政编码加国家本身已经是完全结构化的输入，因此端点无需像处理自由文本字符串那样消除歧义，因为自由文本可能匹配多个名称相近的地点。使用专为这种输入形式构建的端点，可以得到更干净的匹配，出现意外结果的风险也更低。

第二个示例：字母数字混合的邮政编码

对于邮政编码同时使用字母和数字而非仅用数字的国家，同样的调用方式完全适用。

GET /v1/postcode?code=K1A 0B1&country=CA

传入 country 参数是保证可靠性的关键，因为单凭一个编码字符串并不总能在各国之间保持唯一，而 country 参数正是告诉端点应按哪个国家的邮政体系来解读它。

何时仍需要正向地理编码

如果您需要的是具体到街道级别的匹配，而不是邮政编码覆盖的大致区域，那么使用完整地址进行正向地理编码仍然是正确的工具，因为邮政编码查询解析到的是该编码覆盖的区域，而不是其中某栋具体建筑。区域级查询（例如验证配送区域）请使用 /v1/postcode，需要门牌级精度时请使用 /v1/forward。

需要避免的常见错误

不要假定一个邮政编码总是精确对应一个能代表其中所有地址的点。/v1/postcode 返回的坐标代表该编码的覆盖区域，这个区域可能只是一个城市街区，在某些国家也可能是大得多的地带。如果把返回的这个点当作某位客户所在建筑的确切位置，而不是整个编码的代表点，那么在此基础上构建的任何对距离敏感的功能都会引入误差。

在工作流中结合两者

一种常见模式是先用 /v1/postcode 验证邮政编码和国家的组合，验证通过后，再把完整的街道地址发送到 /v1/forward 获取精确坐标。这样每次提交需要两个请求，每个阶段一个，而不是强迫一个端点同时完成两项工作。

边缘情况：没有返回结果的编码

空的 results 数组表示该编码在给定国家中未被识别，这与错误响应是两回事。请像处理其他无法识别的输入一样处理它，请客户重新检查输入的内容，而不是将其显示为系统错误。

成本是多少

每次邮政编码查询计为一个请求，费用与一次正向地理编码查询相同。为结构化输入选择合适的端点并不会改变费用，改变的是您得到正确结果的直接程度。

当您已经有干净的结构化输入时，使用邮政编码端点可以避免为了再把它拆开解析而重新拼接自由文本字符串所带来的额外歧义。完整说明请参阅邮政编码查询文档。

• X
• LinkedIn
• Facebook
• Reddit
• Hacker News
• Telegram
• WhatsApp
• Mastodon
• 电子邮件