您已全部設定完成!

若要開始開發,請參閱我們的開發人員文件

啟用 Google Maps Time Zone API

為協助您開始,我們將先引導您使用「Google 開發人員控制台」來執行一些動作:

  1. 建立或選擇專案
  2. 啟用 Google Maps Time Zone API
  3. 建立適當的金鑰
繼續

開發人員指南

Google Maps Time Zone API 能提供可以要求地球上任何位置的時區,以及該位置時間與 UTC 之間差異的簡單介面。

本文件的適用對象是,想要在其中一個 Google Maps API 提供的地圖上包括時間資料的網站與行動應用程式開發人員。它提供使用 API 的簡介和可用參數的參考資料。

簡介

Google Maps Time Zone API 能提供位於地球表面之位置的時間差異資料。您可以要求特定緯度/經度組合與日期的時區資訊。API 會傳回該時區的名稱、與 UTC 之間的時間差異,以及日光節約時間差異。

您可以透過 HTTPS 介面存取 Google Maps Time Zone API。

在您開始使用 Time Zone API 進行開發之前,請檢閱驗證需求 (您需要 API 金鑰)及 API 使用限制

時區要求

Google Maps Time Zone API 要求是以 URL 字串建構。API 能透過指定的緯度/經度組合,傳回地球任一地點的時區資料。請注意,針對位於水面上(例如海洋)的位置,可能無法提供時區資料。

Google Maps Time Zone API 要求使用下列格式:

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

outputFormat 可以是下列其中一個值:

  • json (建議),指出以 JavaScript 物件標記法 (JSON) 格式輸出;或
  • xml,指出以 XML 格式輸出(包含在 <TimeZoneResponse> 節點內)。

重要:您必須透過 https (而非 http)來提交要求。

注意:URL 必須進行適當編碼才能有效,並針對所有 Web 服務限制為 8192 個字元。請在建構 URL 時注意到此限制。請注意,不同的瀏覽器、Proxy 與伺服器可能也會有不同的 URL 字元限制。

要求參數

根據 URL 標準,所有參數都使用 & 字元來分隔。參數清單與其可能值如下所示。

必要參數

  • location:一個使用逗點分隔的經緯度組合(例如 location=-33.86,151.20),代表要查詢的位置。
  • timestamp 以自 UTC 1970 年 1 月 1 日午夜起所經過之秒數來指定想要的時間。Google Maps Time Zone API 使用 timestamp 來判斷是否需要套用日光節約時間。1970 年之前的時間可以用負值來表示。
  • key - 您應用程式的 API 金鑰。此金鑰會依配額管理目的識別您的應用程式。瞭解如何取得金鑰

    注意:Google Maps APIs Premium Plan 客戶可以在 Time Zone 要求中使用 API 金鑰,或是有效的用戶端編號和數位簽章。如需詳細資訊,請參閱 Premium Plan 客戶的驗證參數

選擇性參數

  • language - 傳回結果時所使用的語言。請參閱支援的地區語言清單。請注意,我們經常更新支援的語言,因此這份清單可能並不詳盡。預設為 en

時區回應

對於每個有效的要求,時區服務將會以要求 URL 內所指出的格式傳回回應。每個回應都包含下列元素:

  • dstOffset:以秒數顯示的日光節約時間差異。如果時區在指定的 timestamp 期間並沒有處於日光節約時間,此值將會是零。
  • rawOffset:指定位置與 UTC 之間的時間差異(以秒數表示)。這將不會把日光節約時間納入考量。
  • timeZoneId:一個包含時區之 "tz" ID 的字串,例如 "America/Los_Angeles" 或 "Australia/Sydney"。這些 ID 是由 IANA 時區資料庫所定義,使用者也能透過 Wikipedia 的 List of tz database time zones 搜尋。
  • timeZoneName:包含時區之完整名稱的字串。如果已設定語言參數,則此欄位將會被當地語系化。例如:「太平洋日光節約時間」或「澳洲東部日光節約時間」
  • status:一個指出回應狀態的字串。
    • OK 指出要求已成功。
    • INVALID_REQUEST 指出要求的格式錯誤。
    • OVER_QUERY_LIMIT 指出要求者已超過配額。
    • REQUEST_DENIED 指出 API 沒有完成要求。請確認要求是透過 HTTPS 而非 HTTP 傳送。
    • UNKNOWN_ERROR 指出不明錯誤。
    • ZERO_RESULTS 指出沒有找到指定位置或時間的時區資料。請確認要求位置是位於陸地上,而非水面上。
  • error_message:除了 OK 之外,有關指定狀態碼背後原因的更多詳細資訊。

    注意:此欄位不保證一律存在,且其內容可能變更。

計算當地時間

所指定位置的當地時間,是結果中的 timestamp 參數,以及 dstOffsetrawOffset 欄位的加總結果。

範例要求

此節包括一些示範 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
需要協助嗎?請前往我們的支援網頁