指南

构建一个简单的“最近办公室”查找工具

只有几处办公室的公司,要回答“哪个办公室离我最近”,并不需要复杂的方案,只需一次地理编码请求,再与一份很少变动的列表做简短比较即可。

对输入进行地理编码

无论访客输入的是地址还是邮政编码,都对其进行地理编码以获取坐标。

GET /v1/forward?q=Berlin, Germany&limit=1
{
  "status": "ok",
  "results": [
    {"formatted": "Berlin, Germany", "lat": 52.5200, "lon": 13.4050, "type": "locality", "precision": "city", "confidence": 0.85, "place_id": "bl456", "components": {"city": "Berlin", "country": "DE"}}
  ]
}

与您的办公室列表比较

请将办公室坐标作为一份小型固定列表保存在您自己的代码或配置中,因为它很少变动,不需要每次单独查询。

offices = [
  {"name": "Berlin", "lat": 52.5170, "lon": 13.3888},
  {"name": "Paris", "lat": 48.8566, "lon": 2.3522},
  {"name": "London", "lat": 51.5074, "lon": -0.1278}
]

使用标准的 haversine 公式计算访客坐标到每个办公室的距离,然后按距离排序并返回最近的一个。

第二个示例:添加输入联想字段

不使用普通文本框,而是让位置字段由 /v1/autocomplete 提供支持,访客在输入时即可从建议的地点中选择,从而降低因拼写错误导致意外地理编码结果的可能。选中某条建议后,通过同样的正向地理编码流程解析其 place_id 或文本,结果会直接进入前面所述的同一距离比较。

处理城市级匹配

请注意,上例中的精度是“city”而不是“house”,因为访客只输入了一个城市名称。这对办公室查找工具来说没有问题,因为目标是从几个选项中挑出最近的办公室,而不是精确定位某栋建筑。与配送地址不同,这里较粗的精度不需要特殊处理。

需要避免的常见错误

当实体办公室开设、关闭或搬迁时,别忘了更新您代码中的固定办公室列表。由于这份列表位于您自己的配置中而不是 API 中,它很容易在不知不觉中过时,悄悄地把访客引向已关闭的地点,或让新办公室完全不参与任何比较。请把这份列表纳入您定期的内容审查,而不是当作一次性的设置步骤。

一个边缘情况:地名有歧义

较短的地名偶尔会匹配到多个真实地点,例如某个国家的地名与别处一个无关地区同名。传入 countries 参数,把候选匹配限制在您实际设有办公室的国家,就能避免这种歧义被解析到世界另一端。

不只显示最近的一个

显示最近的两到三个办公室,而不只是最近的一个,能让位于区域边界附近的访客选择真正适合自己的办公室,例如语言或时区更合适的那个,即使按距离计算稍远一些。

成本是多少

每次搜索就是一次地理编码请求。之后与办公室列表的比较完全在您自己的代码中进行,不会再增加请求数。这样的页面即使流量稳定,也能完全落在每个密钥附带的每天 2,500 次免费请求之内。

这样构建的最近办公室查找工具,每次访客搜索只需要一次请求,实际的比较逻辑完全在您这一侧。请求格式的详细信息请参阅正向地理编码文档