Timezone - Get Timezone By Coordinates

參考

服務:: Maps

API 版本:: 1.0

使用來取得指定之緯度-經度組的目前、歷程記錄和未來的時區資訊。

Get Timezone By Coordinates API 是 HTTP GET 要求，會傳回指定經緯度配對的目前、歷程記錄和未來的時區資訊。此外，API 會提供指定位置的日落和日出時間，但觀測太陽日的區域除外。

GET https://atlas.microsoft.com/timezone/byCoordinates/json?api-version=1.0&query={query}

含選擇性參數:

GET https://atlas.microsoft.com/timezone/byCoordinates/json?api-version=1.0&options={options}&timeStamp={timeStamp}&transitionsFrom={transitionsFrom}&transitionsYears={transitionsYears}&query={query}

URI 參數

名稱	位於	必要	類型	Description
format	path	True	JsonFormat	回應所需的格式。僅支援 `json` 格式。
api-version	query	True	string	Azure 地圖服務 API 的版本號碼。
query	query	True	number[]	要求時區資訊之時間點的座標。此參數是一份座標清單，其中包含一對座標（lat，long）。直接呼叫此端點時，座標會以包含座標的單一字串傳入，並以逗號分隔。
options	query		TimezoneOptions	或者，使用別名 “o”。可用於結果中傳回之資訊類型的選項。
timeStamp	query		string date-time	或者，使用別名 “stamp” 或 “s”。如果省略參考時間，API 會使用提供要求的機器時間。
transitionsFrom	query		string date-time	或者，使用別名「tf」。要求日光節約時間（DST）轉換的開始日期，僅適用於 “options” = all 或 “options” = transitions 時。
transitionsYears	query		integer	或者，使用別名「ty」。要求 DST 轉換的「transitionsFrom」年數，僅適用於 “options” = all 或 “options” = transitions 時。

要求標頭

名稱	必要	類型	Description
x-ms-client-id		string	指定要與 Microsoft Entra ID 安全性模型搭配使用的帳戶。它代表 Azure 地圖服務帳戶的唯一標識碼，而且可以從 Azure 地圖服務管理平面帳戶 API 擷取。若要在 Azure 地圖服務中使用 Microsoft Entra ID 安全性，請參閱下列文章以取得指引。
Accept-Language		string	指定應該傳回時區名稱的語言代碼。如果未提供任何語言代碼，回應會位於「EN」。。如需詳細資訊，請參閱支援的語言。

回應

名稱	類型	Description
200 OK	TimezoneResult	還行
Other Status Codes	ErrorResponse	發生未預期的錯誤。

安全性

AADToken

這些是 Entra OAuth 2.0 流程 Microsoft。與 Azure 角色型存取配對時，控制它可用來控制 Azure 地圖服務 REST API 的存取。 Azure 角色型訪問控制可用來指定一或多個 Azure 地圖服務資源帳戶或子資源的存取權。任何使用者、群組或服務主體都可以透過內建角色或由一或多個 Azure 地圖服務 REST API 許可權所組成的自定義角色來授與存取權。

若要實作案例，建議您檢視驗證概念。總而言之，此安全性定義會透過能夠針對特定 API 和範圍進行訪問控制的物件，提供模型化應用程式的解決方案。

筆記

此安全性定義需要使用 x-ms-client-id 標頭來指出應用程式要求存取的 Azure 地圖服務資源。這可以從地圖管理 API取得。

Authorization URL 專屬於 Azure 公用雲端實例。主權雲端具有唯一的授權 URL，Microsoft Entra ID 設定。 * 透過 Azure 入口網站、PowerShell、CLI、Azure SDK 或 REST API，從 Azure 管理平面設定 Azure 角色型存取控制。 * Azure 地圖服務 Web SDK 的使用方式允許針對多個使用案例設定應用程式。

如需Microsoft身分識別平臺的詳細資訊，請參閱 Microsoft 身分識別平臺概觀。

類型: oauth2
Flow: implicit
授權 URL: https://login.microsoftonline.com/common/oauth2/authorize

範圍

名稱	Description
https://atlas.microsoft.com/.default	https://atlas.microsoft.com/.default

subscription-key

這是當您在 Azure 入口網站或使用 PowerShell、CLI、Azure SDK 或 REST API 建立 Azure 地圖服務帳戶時所佈建的共用密鑰。

使用此金鑰，任何應用程式都可以存取所有 REST API。換句話說，此金鑰可用來做為帳戶中核發的主要密鑰。

針對公開的應用程式，我們建議使用機密用戶端應用程式方法來存取 Azure 地圖服務 REST API，以便安全地儲存您的密鑰。

類型: apiKey
位於: query

SAS Token

這是透過 Azure 入口網站、PowerShell、CLI、Azure SDK 或 REST API，從 azure 地圖服務資源列表 SAS 作業建立共用存取簽章令牌。

使用此令牌時，任何應用程式都有權使用 Azure 角色型訪問控制進行存取，並更精細地控制特定令牌的到期、速率和區域。換句話說，SAS 令牌可用來讓應用程式以比共用密鑰更安全的方式控制存取。

對於公開的應用程式，我們建議在對應帳戶資源上設定允許的來源特定清單，以限制轉譯濫用，並定期更新 SAS 令牌。

類型: apiKey
位於: header

範例

Successfully retrieve timezone by coordinates

範例要求

HTTP

GET https://atlas.microsoft.com/timezone/byCoordinates/json?api-version=1.0&options=all&query=47,-122

範例回覆

狀態碼:: 200

{
  "Version": "2019a",
  "ReferenceUtcTimestamp": "2019-06-17T22:16:59.0765556Z",
  "TimeZones": [
    {
      "Id": "America/Los_Angeles",
      "Aliases": [
        "US/Pacific",
        "US/Pacific-New"
      ],
      "Countries": [
        {
          "Name": "United States",
          "Code": "US"
        }
      ],
      "Names": {
        "ISO6391LanguageCode": "en",
        "Generic": "Pacific Time",
        "Standard": "Pacific Standard Time",
        "Daylight": "Pacific Daylight Time"
      },
      "ReferenceTime": {
        "Tag": "PDT",
        "StandardOffset": "-08:00:00",
        "DaylightSavings": "01:00:00",
        "WallTime": "2019-06-17T15:16:59.0765556-07:00",
        "PosixTzValidYear": 2019,
        "PosixTz": "PST+8PDT,M3.2.0,M11.1.0",
        "Sunrise": "2019-06-17T05:12:21.267-07:00",
        "Sunset": "2019-06-17T21:05:18.017-07:00"
      },
      "RepresentativePoint": {
        "Latitude": 34.05222222222222,
        "Longitude": -118.24277777777777
      },
      "TimeTransitions": [
        {
          "Tag": "PDT",
          "StandardOffset": "-08:00:00",
          "DaylightSavings": "01:00:00",
          "UtcStart": "2019-03-10T10:00:00Z",
          "UtcEnd": "2019-11-03T09:00:00Z"
        },
        {
          "Tag": "PST",
          "StandardOffset": "-08:00:00",
          "DaylightSavings": "00:00:00",
          "UtcStart": "2019-11-03T09:00:00Z",
          "UtcEnd": "2020-03-08T10:00:00Z"
        },
        {
          "Tag": "PDT",
          "StandardOffset": "-08:00:00",
          "DaylightSavings": "01:00:00",
          "UtcStart": "2020-03-08T10:00:00Z",
          "UtcEnd": "2020-11-01T09:00:00Z"
        }
      ]
    }
  ]
}

定義

名稱	Description
CountryRecord	國家/地區記錄。
ErrorAdditionalInfo	資源管理錯誤其他資訊。
ErrorDetail	錯誤詳細數據。
ErrorResponse	錯誤回應
JsonFormat	回應所需的格式。僅支援 `json` 格式。
ReferenceTime	當地時間生效的詳細數據。
RepresentativePoint	代表點屬性
TimeTransition
TimezoneId
TimezoneNames	時區名稱物件。
TimezoneOptions	或者，使用別名 “o”。可用於結果中傳回之資訊類型的選項。
TimezoneResult	這個物件會從成功的時區 By ID 呼叫或依座標呼叫傳回

CountryRecord

國家/地區記錄。

名稱	類型	Description
Code	string	國家/地區的 ISO-3166 2 字母國家/地區代碼。
Name	string	國家/地區名稱

ErrorAdditionalInfo

資源管理錯誤其他資訊。

名稱	類型	Description
info	object	其他資訊。
type	string	其他信息類型。

ErrorDetail

錯誤詳細數據。

名稱	類型	Description
additionalInfo	ErrorAdditionalInfo[]	錯誤其他資訊。
code	string	錯誤碼。
details	ErrorDetail[]	錯誤詳細數據。
message	string	錯誤訊息。
target	string	錯誤目標。

ErrorResponse

錯誤回應

名稱	類型	Description
error	ErrorDetail	error 物件。

JsonFormat

回應所需的格式。僅支援 json 格式。

名稱	類型	Description
json	string	JavaScript 物件表示法數據交換格式

ReferenceTime

當地時間生效的詳細數據。

名稱	類型	Description
DaylightSavings	string	在 `ReferenceUTCTimestamp`上節省幾分鐘的時間。
PosixTz	string	用來設定時區環境變數的POSIX字串。
PosixTzValidYear	integer	這個 POSIX 字串的年份有效。注意：POSIX 字串只有在指定的年份才有效。
StandardOffset	string	在 `ReferenceUTCTimestamp`生效的UTC位移。
Sunrise	string	指定時區的日出，如 `Tag` 屬性所示，只有在呼叫是 `byCoordinates`時填入。日出以 ISO 8601 格式描述。請注意，時區 API 不會在要求的區域觀察到太陽日時傳回日出和日落時間。
Sunset	string	指定時區的日落，如 `Tag` 屬性所示，只有在呼叫 `byCoordinates`時才會填入。日落會以 ISO 8601 格式描述。請注意，時區 API 不會在要求的區域觀察到太陽日時傳回日出和日落時間。
Tag	string	參考時間戳生效的時區名稱（也就是 PST 或 PDT，視日光節約時間是否有效而定）。
WallTime	string	指定時區的目前牆時間，如 `Tag` 屬性所示。

RepresentativePoint

代表點屬性

名稱	類型	Description
Latitude	number	Latitude 屬性
Longitude	number	經度屬性

TimeTransition

名稱	類型	Description
DaylightSavings	string	DaylightSavings 屬性
StandardOffset	string	StandardOffset 屬性
Tag	string	Tag 屬性
UtcEnd	string	結束日期，此轉換期間的結束時間
UtcStart	string	開始日期，此轉換期間的開始時間

TimezoneId

名稱	類型	Description
Aliases	string[]	時區標識元別名的陣列。只有在 [options]=zoneinfo 或所有時才會傳回。注意：可能是 Null。
Countries	CountryRecord[]	國家/地區記錄的陣列。只有在 [options]=zoneinfo 或所有時才會傳回。
Id	string	Id 屬性
Names	TimezoneNames	時區名稱物件。
ReferenceTime	ReferenceTime	當地時間生效的詳細數據。
RepresentativePoint	RepresentativePoint	代表點屬性
TimeTransitions	TimeTransition[]	時區 DST 會從 [transitionsFrom] 轉換到時間戳 + 1 年。

TimezoneNames

時區名稱物件。

名稱	類型	Description
Daylight	string	日光節約名稱
Generic	string	泛型名稱
ISO6391LanguageCode	string	Name 的 ISO 639-1 語言代碼
Standard	string	標準名稱

TimezoneOptions

或者，使用別名 “o”。可用於結果中傳回之資訊類型的選項。

名稱	類型	Description
all	string	在結果中包含 zoneinfo 和轉換。
none	string	請勿在結果中包含 zoneinfo 或轉換。
transitions	string	在結果中包含轉換資訊（轉換數目目前上限為 250）。
zoneInfo	string	在結果中包含其他時區資訊。

TimezoneResult

這個物件會從成功的時區 By ID 呼叫或依座標呼叫傳回

名稱	類型	Description
ReferenceUtcTimestamp	string	參考Utc Timestamp屬性
TimeZones	TimezoneId[]	TimeZoneId 陣列
Version	string	Version 屬性

共用方式為