時區要求和回應

時區

Time Zone API 要求會以網址字串的形式建構。API 會傳回地球上某個點的時間區資料，該點由經緯度組合指定。請注意，系統可能無法提供水上位置 (例如海洋或海) 的時區資料。

時區要求的格式如下：

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

其中 outputFormat 可為下列其中一個值：

  • json (建議使用) 表示輸出內容格式為 JavaScript 物件標記法 (JSON)；或
  • xml：表示以 XML 格式輸出，並在 <TimeZoneResponse> 節點中包裝。

注意：網址必須經過正確編碼才有效，而且所有網路服務的長度上限為 16384 個字元。建立網址時請注意這項限制。請注意，不同瀏覽器、代理程式和伺服器的網址字元限制也可能不同。

Required parameters

  • location

    A comma-separated latitude,longitude tuple, location=39.6034810,-119.6822510, representing the location to look up.

  • timestamp

    The desired time as seconds since midnight, January 1, 1970 UTC. The Time Zone API uses the timestamp to determine whether or not Daylight Savings should be applied, based on the time zone of the location.

    Note that the API does not take historical time zones into account. That is, if you specify a past timestamp, the API does not take into account the possibility that the location was previously in a different time zone.

Optional parameters

  • language

    The language in which to return results.

    • See the list of supported languages. Google often updates the supported languages, so this list may not be exhaustive.
    • If language is not supplied, the API attempts to use the preferred language as specified in the Accept-Language header.
    • The API does its best to provide a street address that is readable for both the user and locals. To achieve that goal, it returns street addresses in the local language, transliterated to a script readable by the user if necessary, observing the preferred language. All other addresses are returned in the preferred language. Address components are all returned in the same language, which is chosen from the first component.
    • If a name is not available in the preferred language, the API uses the closest match.
    • The preferred language has a small influence on the set of results that the API chooses to return, and the order in which they are returned. The geocoder interprets abbreviations differently depending on language, such as the abbreviations for street types, or synonyms that may be valid in one language but not in another. For example, utca and tér are synonyms for street in Hungarian.

時區範例

本節包含一些範例查詢，可展示 API 的功能。

以下查詢會執行美國內華達州的時區要求。時間戳記設為 2012 年 3 月 8 日。

網址

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

cURL

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

JSON

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

XML

<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 日。回應現在包含日光節約時間偏移。

網址

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

cURL

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

JSON

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

XML

<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
  &timestamp=1331766000
  &key=YOUR_API_KEY

cURL

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

JSON

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

XML

<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

FieldRequiredTypeDescription
requiredTimeZoneStatus See TimeZoneStatus for more information.
optionalnumber

The offset for daylight-savings time in seconds. This will be zero if the time zone is not in Daylight Savings Time during the specified timestamp.

optionalstring

Detailed information about the reasons behind the given status code. Included if status other than Ok.

optionalnumber

The offset from UTC (in seconds) for the given location. This does not take into effect daylight savings.

optionalstring

a string containing the ID of the time zone, such as "America/Los_Angeles" or "Australia/Sydney". These IDs are defined by Unicode Common Locale Data Repository (CLDR) project, and currently available in file timezone.xml. When a timezone has several IDs, the canonical one is returned. In xml responses, this is the first alias of each timezone. For example, "Asia/Calcutta" is returned, not "Asia/Kolkata".

optionalstring

The long form name of the time zone. This field will be localized if the language parameter is set. eg. Pacific Daylight Time or Australian Eastern Daylight Time.

TimeZoneStatus

The status field within the Time Zone response object contains the status of the request. The status field may contain the following values:

  • OK indicates that the request was successful.

  • INVALID_REQUEST indicates that the request was malformed.

  • OVER_DAILY_LIMIT indicates any of the following:

    • The API key is missing or invalid.
    • Billing has not been enabled on your account.
    • A self-imposed usage cap has been exceeded.
    • The provided method of payment is no longer valid (for example, a credit card has expired).

  • OVER_QUERY_LIMIT indicates the requestor has exceeded quota.

  • REQUEST_DENIED indicates that the API did not complete the request. Confirm that the request was sent over HTTPS instead of HTTP.

  • UNKNOWN_ERROR indicates an unknown error.

  • ZERO_RESULTS indicates that no time zone data could be found for the specified position or time. Confirm that the request is for a location on land, and not over water.

正在計算當地時間

特定地點的本地時間是 timestamp 參數和結果中的 dstOffset 和 rawOffset 欄位的總和。