查找任意经纬度所在的时区

仅凭坐标无法知道地图上某一点现在是几点。时区端点接收纬度和经度，返回时区名称、当前 UTC 偏移量和时区缩写。

GET /v1/timezone?lat=52.3676&lon=4.9041

{
  "status": "ok",
  "timezone": "Europe/Amsterdam",
  "utc_offset": "+02:00",
  "abbreviation": "CEST"
}

timezone 字段是一个标准标识符，您可以直接将其传入大多数日期和时间库。utc_offset 和 abbreviation 字段适合用于显示，当您想向读者展示比标识符字符串更熟悉的内容时非常有用。

偏移量并不总是较小的整数，而且有些地方与世界上大多数人口分处国际日期变更线的两侧。

GET /v1/timezone?lat=-17.7333&lon=168.3273

{
  "status": "ok",
  "timezone": "Pacific/Efate",
  "utc_offset": "+11:00",
  "abbreviation": "VUT"
}

无论返回的标识符与您服务器的时钟相差多远，都以同样的方式处理它。您的日期库已经知道如何正确处理十一个小时的偏移，因此对于远离您所在时区的位置，无需编写任何特殊处理逻辑。

该端点只需要坐标，因此天然适合与正向或逆地理编码搭配使用。先对地址进行地理编码以获得其纬度和经度，再将其直接传入 /v1/timezone，即可得知该位置所在的时区，而无需直接询问用户任何有关时区的问题。

如果您手头已有访客的 IP 地址，而不是经过地理编码的地址，/v1/ip 端点会在其响应中直接返回 timezone 字段，完全无需单独调用本端点。当您已有坐标但没有相关的 IP 查询时，例如来自客户收货资料中的地址，请直接使用 /v1/timezone。

utc_offset 和 abbreviation 反映的是您所查询时间点上生效的偏移量。如果您关心的是某个特定日期而不是现在，请通过 time 参数传入一个 Unix 时间戳，这样响应反映的就是该日期适用的偏移量，而不是今天的偏移量。

GET /v1/timezone?lat=52.3676&lon=4.9041&time=1731000000

调用一次该端点并长期缓存 utc_offset 值是一种常见的捷径，但在实行夏令时的地方，这种做法每年会出错两次。时区标识符本身是稳定的，可以放心缓存。偏移量和缩写则不然，它们会随日历变化，因此请在显示时重新计算，而不要将其与标识符一起存储。

每次时区查询计为一个请求。如果您已经在注册或结账流程中对地址进行地理编码，为同一位置增加一次时区查询会使该流程的请求数翻倍，从一个请求变为两个，相比每个密钥附带的每天 2,500 次免费请求，这仍然微不足道。

时区数据手动处理很容易出错，尤其是在夏令时切换前后，因此值得从单一来源获取，而不是自己维护一张偏移量表。时区查询文档列出了完整的参数。

查找任意经纬度的时区