一切就绪！

着手开发前，请先阅读我们的开发者文档。

激活 Google Maps Time Zone API

为帮助您起步，我们将引导您在 Google Developers Console 中先完成几项任务：

  1. 创建或选择项目
  2. 激活 Google Maps Time Zone API
  3. 创建相应密钥
继续

开发人员指南

Google Maps Time Zone API 提供了一个用于请求地球上某个位置的时区以及该位置与协调世界时的时间偏移的简单接口。

Java Client、Python Client、Go Client 和 Node.js Client for Google Maps Services 中也提供了该服务。

本文档的适用对象是想要在其中一个 Google Maps API 提供的地图上加入时间数据的网站和移动开发者。它介绍了 API 使用方法，并提供了有关可用参数的参考资料。

简介

Google Maps Time Zone API 提供地球表明各位置的时间偏移数据。您可以请求特定纬度/经度对和日期的时区信息。该 API 将返回该时区的名称、与协调世界时的时间偏移以及夏令时偏移。

您可以通过 HTTPS 接口访问 Google Maps Time Zone API。

在开始使用 Time Zone API 进行开发前，请查看身份验证要求（需要 API 密钥）和 API 使用限额。

时区请求

Google Maps Time Zone API 请求以网址字符串形式构建。该 API 返回地球上由纬度/经度对所指定地点的时区数据。请注意，可能无法获得水上（如大洋或海上）位置的时区数据。

Google Maps Time Zone API 请求使用以下格式：

https://maps.googleapis.com/maps/api/timezone/outputFormat?parameters

其中 outputFormat 可以是以下值之一：

  • json（推荐），表示以 JavaScript 对象标记 (JSON) 格式输出；或
  • xml，表示以 XML 格式输出，结果包装在 <TimeZoneResponse> 节点内。

重要说明：您必须通过 https 而非 http 提交请求。

注：网址必须编码正确方有效，并且对于所有网络服务，均有 8192 字符数限制。请在构建网址时注意这一限制。请注意，不同的浏览器、代理和服务器可能同样具有不同的 URL 字符限制。

请求参数

依照所有 URL 的标准，参数使用“与”字符 (&) 分隔。下面列出了各个参数及其可能的值。

必填参数

  • location：逗号分隔的 lat,lng 元组（例如：location=-33.86,151.20），表示要查询的位置。
  • timestamp：表示所需时间，以协调世界时 1970 年 1 月 1 日午夜以来的秒数表示。Google Maps Time Zone API 使用 timestamp 来确定是否应该应用夏令时。1970 年之前的时间可表示为负值。
  • key – 您的应用的 API 密钥。此密钥可以标识您的应用，以便进行配额管理。了解如何获取密钥。

    注：Google Maps APIs Premium Plan 客户可以在 Time Zone 请求中使用 API 密钥或有效的客户端 ID 和数字签名。获取有关 Premium Plan 客户身份验证参数的更多信息。

可选参数

  • language – 返回结果时使用的语言。请参阅支持的区域语言列表。请注意，我们会经常更新支持的语言，因此，此列表可能并不全面。默认值为 en。

时区响应

对于每个有效的请求，时区服务都会以请求 URL 内指定的格式返回响应。每个响应都包含以下元素：

  • dstOffset：以秒数表示的夏令时偏移。如果在指定 timestamp 期间时区未执行夏令时，该值将为零。
  • rawOffset：给定位置与协调世界时的偏移（单位：秒）。该值未将夏令时考虑在内。
  • timeZoneId：一个包含时区“tz”ID 的字符串，如“America/Los_Angeles”或“Australia/Sydney”。这些 ID 在 IANA 时区数据库内定义，Wikipedia 的 tz 数据库时区列表中还提供了该数据库的可搜索格式。
  • timeZoneName：一个包含时区完整形式名称的字符串。如果设置了语言参数，此字段将设置为本地化值，例如：“Pacific Daylight Time”或“Australian Eastern Daylight Time”
  • status：一个表示响应状态的字符串。
    • OK 表示请求成功
    • INVALID_REQUEST 表示请求的格式不正确
    • OVER_QUERY_LIMIT 表示请求者超过了配额
    • REQUEST_DENIED 表示 API 未完成请求。确认请求是通过 HTTPS 而非 HTTP 发送的
    • UNKNOWN_ERROR 表示未知错误
    • ZERO_RESULTS 表示找不到指定位置或时间的时区数据。确认请求针对的位置位于陆地上而不是水上
  • error_message：当给定状态代码不是 OK 时，更详细地说明其背后的原因。

    注：此字段不保证始终出现，并且其内容可能会更改。

计算本地时间

给定位置的本地时间是 timestamp 参数与结果中 dstOffset 字段和 rawOffset 字段之和。

示例请求

此部分包括的一些示例查询展示了 API 的功能。

以下查询请求获得美国内华达州的时区。时间戳设置为 2012 年 3 月 8 日。

JSON

请求：

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

响应：

{
   "dstOffset" : 0,
   "rawOffset" : -28800,
   "status" : "OK",
   "timeZoneId" : "America/Los_Angeles",
   "timeZoneName" : "Pacific Standard Time"
}
XML

请求：

https://maps.googleapis.com/maps/api/timezone/xml?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

响应：

<TimeZoneResponse>
  <status>OK</status>
  <raw_offset>-28800.0000000</raw_offset>
  <dst_offset>0.0000000</dst_offset>
  <time_zone_id>America/Los_Angeles</time_zone_id>
  <time_zone_name>Pacific Standard Time</time_zone_name>
</TimeZoneResponse>

以下查询请求获得美国内华达州的时区。位置与以上请求相同，但时间戳设置为 2012 年 3 月 15 日。响应现在包括了夏令时偏移。

JSON

请求：

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331766000&key=YOUR_API_KEY

响应：

{
   "dstOffset" : 3600,
   "rawOffset" : -28800,
   "status" : "OK",
   "timeZoneId" : "America/Los_Angeles",
   "timeZoneName" : "Pacific Daylight Time"
}
XML

请求：

https://maps.googleapis.com/maps/api/timezone/xml?location=39.6034810,-119.6822510&timestamp=1331766000&key=YOUR_API_KEY

响应：

<TimeZoneResponse>
  <status>OK</status>
  <raw_offset>-28800.0000000</raw_offset>
  <dst_offset>3600.0000000</dst_offset>
  <time_zone_id>America/Los_Angeles</time_zone_id>
  <time_zone_name>Pacific Daylight Time</time_zone_name>
</TimeZoneResponse>

此示例与以上两例类似，不同的是设置了语言参数。响应现在将本地化为西班牙语。

JSON

请求：

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331766000&language=es&key=YOUR_API_KEY

响应：

{
   "dstOffset" : 3600,
   "rawOffset" : -28800,
   "status" : "OK",
   "timeZoneId" : "America/Los_Angeles",
   "timeZoneName" : "Hora de verano del Pacífico"
}
XML

请求：

https://maps.googleapis.com/maps/api/timezone/xml?location=39.6034810,-119.6822510&timestamp=1331766000&language=es&key=YOUR_API_KEY

响应：

<TimeZoneResponse>
  <status>OK</status>
  <raw_offset>-28800.0000000</raw_offset>
  <dst_offset>3600.0000000</dst_offset>
  <time_zone_id>America/Los_Angeles</time_zone_id>
  <time_zone_name>Hora de verano del Pacífico</time_zone_name>
</TimeZoneResponse>

sensor 参数

Google Maps API 之前要求您将 sensor 参数包括在内，以指示您的应用是否使用传感器来确定用户的位置。但该参数现在不再是必填项。

发送以下问题的反馈：

此网页
文档反馈
Google Maps Time Zone API
Google Maps Time Zone API
产品反馈
需要帮助？请访问我们的支持页面。