時區要求和回應

時區

Time Zone API 要求是以網址字串的形式建構。API 會傳回地球上某個點的時區資料，該點由經緯度組合指定。請注意，海洋或海域等水域位置可能沒有時區資料。

Time Zone 要求採用以下格式：

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

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

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

必要參數

位置

以半形逗號分隔的經緯度元組 location=39.6034810,-119.6822510，代表要查詢的位置。

時間戳記

預定時間，以自世界標準時間 1970 年 1 月 1 日午夜起的秒數表示。Time Zone API 會根據 location 的時區，使用 timestamp 判斷是否應套用日光節約時間。

請注意，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,-119.6822510&timestamp=1733428634&key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1733428634&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>

以下查詢會對美國內華達州提出時區要求。位置與上述要求相同，但時間戳記設為 2024 年 3 月 15 日。回應現在包含日光節約時間偏移。

網址

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

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1710547034&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,-119.6822510&timestamp=1710547034&key=YOUR_API_KEY

curl

curl -L -X GET 'https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1710547034&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

欄位 必填 類型 說明
required TimeZoneStatus 詳情請參閱 TimeZoneStatus。
選填 數字

日光節約時間的時差 (以秒為單位)。如果時區在指定的 timestamp 期間不屬於日光節約時間，則這個值會是零。
選填 字串

提供狀態碼的詳細原因。 如果狀態不是 Ok，則會包含。

選填 數字

指定位置與世界標準時間 (UTC) 的時差 (以秒為單位)。這不會影響日光節約時間。
選填 字串

包含時區 ID 的字串，例如「America/Los_Angeles」或「Australia/Sydney」。這些 ID 是由萬國碼 (Unicode) 通用語言代碼資料存放區 (CLDR) 專案定義，目前可在 timezone.xml 檔案中找到。如果時區有多個 ID，系統會傳回標準 ID。在 XML 回應中，這是每個時區的第一個別名。例如，系統會傳回「Asia/Calcutta」，而非「Asia/Kolkata」。

選填 字串

時區的完整名稱。如果設定語言參數，這個欄位就會本地化。例如：Pacific Daylight Time 或 Australian Eastern Daylight Time。

TimeZoneStatus

Time Zone 回應物件中的 status 欄位包含要求狀態。status 欄位可能包含下列值：

  • OK 表示要求成功。

  • INVALID_REQUEST 表示要求格式有誤。

  • OVER_DAILY_LIMIT 表示下列任一情況：

    • API 金鑰遺失或無效。
    • 您的帳戶未啟用計費功能。
    • 超過自行設定的用量上限。
    • 您提供的付款方式已失效 (例如信用卡已過期)。

  • OVER_QUERY_LIMIT：表示要求者已超出配額。

  • REQUEST_DENIED 表示 API 未完成要求。確認要求是透過 HTTPS (而非 HTTP) 傳送。

  • UNKNOWN_ERROR 表示發生不明錯誤。

  • ZERO_RESULTS 表示找不到指定位置或時間的時區資料。確認要求的是陸地位置，而非水上位置。

計算當地時間

指定位置的當地時間是 timestamp 參數，以及結果中 dstOffset 和 rawOffset 欄位的總和。