My Geocode

指南

将自由文本地址字段解析为结构化组成部分

· 阅读约 3 分钟 · My Geocode · #forward-geocoding#address-parsing#data-structure

单一的自由文本地址字段收集起来容易，事后处理起来却很难，尤其是当您需要按城市筛选或按地区分组时。正向地理编码在把地址解析为坐标的同时，顺带为您完成了拆分。

发送自由文本

GET /v1/forward?q=1600 Pennsylvania Avenue, Washington, DC 20500&limit=1
{
  "status": "ok",
  "query": "1600 Pennsylvania Avenue, Washington, DC 20500",
  "results": [
    {
      "formatted": "1600 Pennsylvania Avenue NW, Washington, DC 20500",
      "lat": 38.8977,
      "lon": -77.0365,
      "type": "address",
      "precision": "house",
      "confidence": 0.97,
      "place_id": "def456",
      "components": {"house_number": "1600", "street": "Pennsylvania Avenue NW", "city": "Washington", "region": "DC", "postcode": "20500", "country": "US"}
    }
  ]
}

分别存储各个组成部分

拿到 components 对象后，把每个字段写入各自的数据库列，而不是只保留原始的自由文本字符串。这样就可以按城市或地区筛选客户记录，生成准确的地区报告，并验证邮政编码和城市是否确实匹配，而这些对单一的非结构化字符串来说都不现实。

第二个例子：另一种格式的地址

地址结构并非处处相同。英国地址解析后可能用郡代替美国式的地区，而对于有名称的建筑，house_number 之类的组成部分可能完全不存在。无论哪个国家，发送同样格式的请求都可以，但实际返回的组成部分键可能不同，因此请把存储结构设计为能够容忍某个组成部分缺失，而不要假定每个国家每次都会填入完全相同的一组字段。

需要避免的常见错误

不要在代码中写死一个假设，认为每个结果都会包含 house_number、street、city、region 和 postcode 全部字段，然后把缺少其中任何一个的地址都视为解析错误。一个完全有效的地址，尤其是在有门牌号的城市街区之外，完全可能返回部分字段为空。围绕完整组成部分构建严格验证，会拒绝端点已正确解析的真实客户输入。

同时保留原始文本

把原始的自由文本输入与解析后的组成部分一起存储，而不是丢弃它。如果某个组成部分返回不完整，或者客户之后需要更正某些内容，手头有原始文本会让重新解析或手动更正变得简单。

处理部分解析

并不是每个地址解析后都会填满所有组成部分。农村地址可能没有 house_number，小城镇可能没有单独的地区值。请把缺失的组成部分字段视为合理的空值，而不是解析失败，当您想要的某个组成部分不存在时，改用 formatted 字符串来显示。

处理多个可能的匹配

将 limit 提高到 1 以上时，会返回多个候选结果，按各自与自由文本的匹配程度排序。当您希望向客户展示一个简短的选择列表，而不是默默采用排名第一的匹配时，这一点很有用。对于完全自动解析和完全手动填写的表单来说，这是一个合理的折中方案，尤其适用于那些原本会被您的置信度阈值标记为不确定的地址。

成本是多少

以这种方式解析自由文本字段，每个地址消耗一次请求，与其他任何正向地理编码查询相同。清理现有自由文本地址表的回填任务可以把整张表作为批量请求处理，每行一次请求。

把自由文本转换为结构化字段，是对地址进行地理编码时自然产生的附带结果，而不是额外的步骤。正向地理编码文档列出了该端点可以返回的所有组成部分。

更多指南

· 阅读约 4 分钟

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

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