时区请求和响应

时区

时区 API 请求以网址字符串的形式构建。该 API 会返回地球上某个点的时区 数据，该点由纬度/经度对指定。请注意，时区数据可能不适用于水上位置，例如海洋或海域。

时区请求采用以下形式：

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

其中，outputFormat 可以是以下任一值：

• json（推荐），表示以 JavaScript 对象表示法 (JSON) 输出；或
• xml，表示以 XML 输出，封装在 <TimeZoneResponse> 节点内。

注意：网址必须 经过正确编码 才能有效，并且对于所有 Web 服务，网址长度不得超过 16384 个字符。构建网址时请注意此限制。另请注意，不同的浏览器、代理和服务器也可能有不同的网址字符数限制。

必需参数

• location

  以逗号分隔的纬度、经度元组， location=39.6034810,-119.6822510，表示要查找的位置。

• timestamp

  自世界协调时间 (UTC) 1970 年 1 月 1 日午夜起计算的秒数，表示所需时间。时区 API 使用 timestamp 根据 location 的时区确定是否应应用夏令时。

  请注意，该 API 不考虑历史时区。也就是说，如果您指定过去的时间戳，该 API 不会考虑该位置之前可能处于不同时区的情况。

可选参数

• language

  返回结果所用的语言。

  • 请参阅 支持的语言列表。Google 会经常更新支持的语言，因此该列表可能并非详尽无遗。
  • 如果未提供 language，该 API 会尝试使用 Accept-Language 标头中指定的首选语言。
  • 该 API 会尽力提供用户和当地人都能看懂的街道地址。为实现此目标，它会以当地语言返回街道地址，并在必要时根据首选语言将街道地址音译为用户可读的脚本。所有其他 地址均以首选语言返回。地址组成部分均以同一种语言返回，该语言从第一个组成部分中选择。
  • 如果首选语言中没有名称，该 API 会使用最接近的匹配项。
  • 首选语言对 API 选择返回的结果集以及返回结果的顺序影响不大。地理编码器会根据语言以不同的方式解读缩写，例如街道类型的缩写，或者在一种语言中有效但在另一种语言中无效的同义词。例如，在匈牙利语中，utca 和 tér 是街道的同义词。

时区示例

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

以下查询针对美国内华达州执行时区请求。时间戳设置为 2024 年 12 月 5 日。

https://maps.googleapis.com/maps/api/timezone/json
  ?location=39.6034810%2C-119.6822510
  ×tamp=1733428634
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510×tamp=1733428634&key=YOUR_API_KEY'

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

<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>
      

以下查询针对美国内华达州执行时区请求。位置 与上述请求相同，但时间戳设置为 3 月 15 日 2024 年。响应现在包括了夏令时偏移值。

https://maps.googleapis.com/maps/api/timezone/json
  ?location=39.6034810%2C-119.6822510
  ×tamp=1710547034
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510×tamp=1710547034&key=YOUR_API_KEY'

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

<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>

此示例与上述两个示例类似，但设置了语言参数。 响应现在将本地化为西班牙语。

https://maps.googleapis.com/maps/api/timezone/json
  ?language=es
  &location=39.6034810%2C-119.6822510
  ×tamp=1710547034
  &key=YOUR_API_KEY

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810%2C-119.6822510×tamp=1710547034&language=es&key=YOUR_API_KEY'

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

<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>
      

时区响应

对于每个有效请求，时区都会以请求网址中指示的 格式返回响应。

TimeZoneResponse

TimeZoneStatus

时区响应对象中的 status 字段包含 请求的状态。status 字段可能包含以下值：

• OK 表示请求成功。

• INVALID_REQUEST 表示请求格式错误。

• OVER_DAILY_LIMIT 表示以下任一情况：

  • API 密钥缺失或无效。
  • 您的账号未启用结算功能。
  • 超出了您设定的用量上限。
  • 提供的付款方式不再有效（例如，信用卡已过期）。

• OVER_QUERY_LIMIT 表示请求者超出了配额。

• REQUEST_DENIED 表示 API 未完成 请求。确认请求是通过 HTTPS 而不是 HTTP 发送的。

• UNKNOWN_ERROR 表示未知错误。

• ZERO_RESULTS 表示找不到指定位置或时间的时区数据 。确认请求是针对陆地上的 位置，而不是水上位置。

计算当地时间

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