時區要求和回應

時區

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

時區要求的格式如下：

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

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

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

注意：網址必須經過適當編碼，才能有效使用，且所有網路服務的網址長度上限為 16,384 個字元。建構網址時，請注意這項限制。請注意，不同的瀏覽器、Proxy 和伺服器也可能有不同的網址字元限制。

必要參數

位置

以半形逗號分隔的經緯度元組，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%2C-119.6822510
  ×tamp=1733428634
  &key=YOUR_API_KEY

curl

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

curl

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

curl

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'

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

欄位	必填	類型	說明
`status`	required	TimeZoneStatus	詳情請參閱 TimeZoneStatus。
`dstOffset`	選用	數字	日光節約時間的時差 (以秒為單位)。如果指定 `timestamp` 時，時區並未採用日光節約時間，這個值就會是零。
`errorMessage`	選用	字串	詳細說明指定狀態碼背後的原因。如果狀態不是 `Ok`，則會包含這項資訊。
`rawOffset`	選用	數字	指定位置與世界標準時間的時差 (以秒為單位)。這不會受到日光節約時間影響。
`timeZoneId`	選用	字串	包含時區 ID 的字串，例如「America/Los_Angeles」或「Australia/Sydney」。這些 ID 是由 Unicode 通用區域資料庫 (CLDR) 專案定義，目前可在 timezone.xml 檔案中使用。如果時區有多個 ID，系統會傳回標準 ID。在 XML 回應中，這是每個時區的第一個別名。舉例來說，系統會傳回「Asia/Calcutta」，而不是「Asia/Kolkata」。
`timeZoneName`	選用	字串	時區的完整名稱。如果設定語言參數，這個欄位就會經過本地化。例如：`Pacific Daylight Time` 或 `Australian Eastern Daylight Time`。

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 欄位總和。

時區要求和回應

時區

必要參數

位置

時間戳記

選用參數

language

時區範例

網址

curl

JSON

XML

網址

curl

JSON

XML

網址

curl

JSON

XML

時區回覆

TimeZoneResponse

`status`

`dstOffset`

`errorMessage`

`rawOffset`

`timeZoneId`

`timeZoneName`

TimeZoneStatus

計算當地時間

時區要求和回應 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

時區

必要參數

位置

時間戳記

選用參數

language

時區範例

網址

curl

JSON

XML

網址

curl

JSON

XML

網址

curl

JSON

XML

時區回覆

TimeZoneResponse

status

dstOffset

errorMessage

rawOffset

timeZoneId

timeZoneName

TimeZoneStatus

計算當地時間

時區要求和回應

`status`

`dstOffset`

`errorMessage`

`rawOffset`

`timeZoneId`

`timeZoneName`