Weather - Get Weather Along Route

參考

服務:: Maps

API 版本:: 1.1

用於獲取位置精確的 up-to即時預報，其中包括沿路線的天氣災害評估和通知。

該 Get Weather Along Route API 是一個 HTTP GET 請求，可返回超本地（一公里或更短）、up-to分鐘天氣臨近預報、天氣災害評估和沿路線的通知，這些路徑被描述為一系列航點。這包括影響航點或路線的天氣災害清單，每個航點的聚合危險指數可用於根據對駕駛員的安全程度來繪製路線的每個部分。提交航點時，建議保持在120分鐘內或之後不久可以行駛的距離內或附近。數據每 5 分鐘更新一次。

該服務是對 Azure Maps 路線服務的補充，該服務允許你首先請求起點和目的地之間的路線，並將其用作沿路線天氣終結點的輸入。

此外，該服務還支援為天氣災害強度增加的航點生成天氣通知的場景。例如，如果預計車輛在到達某個航點時將開始下大雨，則會為該航點生成大雨天氣通知，從而允許最終產品在駕駛員到達該航點之前顯示大雨通知。例如，何時顯示航點通知的觸發器可以基於地理圍欄或到航點的可選距離。

API 覆蓋了地球上除格陵蘭島和南極洲以上緯度以外的所有地區。

GET https://atlas.microsoft.com/weather/route/json?api-version=1.1&query={query}

含選擇性參數:

GET https://atlas.microsoft.com/weather/route/json?api-version=1.1&query={query}&language={language}

URI 參數

名稱	位於	必要	類型	Description
format	path	True	JsonFormat	回應所需的格式。僅支援 `json` 格式。
api-version	query	True	string	Azure 地圖服務 API 的版本號碼。
query	query	True	string	計算路線的座標，用冒號（:) 分隔，並按時間順序輸入。至少需要兩個航點。單個 API 調用最多可包含 60 個航點。航點指示位置、ETA 和可選航向：latitude、longitude、ETA、heading，其中 `Latitude` - 以十進制度為單位的緯度座標。 `Longitude` - 以十進制度為單位的經度座標。 `ETA (estimated time of arrival)` - 從當前時間開始，無人機到達航點所需的分鐘數。允許的範圍為 0.0 到 120.0 分鐘。 `Heading` - 一個可選值，指示無人機在通過航點時的航向。以相對於真北的順時針度數表示。發佈此數據是為了計算作為駕駛危險的眩光。允許的範圍為 0.0 到 360.0 度。如果未提供，將根據相鄰航點的位置自動得出航向。建議保持在120分鐘內或之後不久可以行駛的距離內或附近。這樣就可以為行程提供更準確的評估，並防止在航點之間無法捕獲孤立的事件。可以而且應該沿路線更新資訊（尤其是對於超過 2 小時的行程），以不斷向前移動新的航點，同時也要確保隨著風暴的發展和消散，降水類型和強度等內容的預報資訊是準確的。
language	query		string	應該傳回搜尋結果的語言。應該是其中一個支援的 IETF 語言標記，不區分大小寫。當特定欄位無法使用指定語言的數據時，會使用預設語言。如需詳細資訊，請參閱支援的語言。

要求標頭

名稱	必要	類型	Description
x-ms-client-id		string	指定要與 Microsoft Entra ID 安全性模型搭配使用的帳戶。它代表 Azure 地圖服務帳戶的唯一標識碼，而且可以從 Azure 地圖服務管理平面帳戶 API 擷取。若要在 Azure 地圖服務中使用 Microsoft Entra ID 安全性，請參閱下列文章以取得指引。

回應

名稱	類型	Description
200 OK	WeatherAlongRouteResult	還行
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 detailed weather casts along a route described as a sequence of waypoints

範例要求

HTTP

GET https://atlas.microsoft.com/weather/route/json?api-version=1.1&query=38.907,-77.037,0:38.907,-77.009,10:38.926,-76.928,20:39.033,-76.852,30:39.168,-76.732,40:39.269,-76.634,50:39.287,-76.612,60

範例回覆

狀態碼:: 200

{
  "summary": {
    "iconCode": 35,
    "hazards": {
      "maxHazardIndex": 0
    }
  },
  "waypoints": [
    {
      "iconCode": 38,
      "shortPhrase": "Mostly cloudy",
      "isDayTime": false,
      "cloudCover": 70,
      "temperature": {
        "value": 3.4,
        "unit": "C",
        "unitType": 17
      },
      "wind": {
        "direction": {
          "degrees": 142
        },
        "speed": {
          "value": 2,
          "unit": "km/h",
          "unitType": 7
        }
      },
      "windGust": {
        "speed": {
          "value": 3,
          "unit": "km/h",
          "unitType": 7
        }
      },
      "precipitation": {
        "dbz": 0,
        "type": "SNOW"
      },
      "lightningCount": 0,
      "sunGlare": {
        "calculatedVehicleHeading": 90,
        "glareIndex": 0
      },
      "hazards": {
        "maxHazardIndex": 0
      },
      "notifications": []
    },
    {
      "iconCode": 38,
      "shortPhrase": "Mostly cloudy",
      "isDayTime": false,
      "cloudCover": 65,
      "temperature": {
        "value": 3.4,
        "unit": "C",
        "unitType": 17
      },
      "wind": {
        "direction": {
          "degrees": 166
        },
        "speed": {
          "value": 1,
          "unit": "km/h",
          "unitType": 7
        }
      },
      "windGust": {
        "speed": {
          "value": 2,
          "unit": "km/h",
          "unitType": 7
        }
      },
      "precipitation": {
        "dbz": 0,
        "type": "SNOW"
      },
      "lightningCount": 0,
      "sunGlare": {
        "calculatedVehicleHeading": 77,
        "glareIndex": 0
      },
      "hazards": {
        "maxHazardIndex": 0
      },
      "notifications": []
    },
    {
      "iconCode": 35,
      "shortPhrase": "Partly cloudy",
      "isDayTime": false,
      "cloudCover": 43,
      "temperature": {
        "value": 3.2,
        "unit": "C",
        "unitType": 17
      },
      "wind": {
        "direction": {
          "degrees": 163
        },
        "speed": {
          "value": 2,
          "unit": "km/h",
          "unitType": 7
        }
      },
      "windGust": {
        "speed": {
          "value": 2,
          "unit": "km/h",
          "unitType": 7
        }
      },
      "precipitation": {
        "dbz": 0,
        "type": "SNOW"
      },
      "lightningCount": 0,
      "sunGlare": {
        "calculatedVehicleHeading": 44,
        "glareIndex": 0
      },
      "hazards": {
        "maxHazardIndex": 0
      },
      "notifications": []
    },
    {
      "iconCode": 35,
      "shortPhrase": "Partly cloudy",
      "isDayTime": false,
      "cloudCover": 34,
      "temperature": {
        "value": 1.6,
        "unit": "C",
        "unitType": 17
      },
      "wind": {
        "direction": {
          "degrees": 189
        },
        "speed": {
          "value": 2,
          "unit": "km/h",
          "unitType": 7
        }
      },
      "windGust": {
        "speed": {
          "value": 4,
          "unit": "km/h",
          "unitType": 7
        }
      },
      "precipitation": {
        "dbz": 0,
        "type": "SNOW"
      },
      "lightningCount": 0,
      "sunGlare": {
        "calculatedVehicleHeading": 32,
        "glareIndex": 0
      },
      "hazards": {
        "maxHazardIndex": 0
      },
      "notifications": []
    },
    {
      "iconCode": 38,
      "shortPhrase": "Mostly cloudy",
      "isDayTime": false,
      "cloudCover": 54,
      "temperature": {
        "value": 0.5,
        "unit": "C",
        "unitType": 17
      },
      "wind": {
        "direction": {
          "degrees": 202
        },
        "speed": {
          "value": 4,
          "unit": "km/h",
          "unitType": 7
        }
      },
      "windGust": {
        "speed": {
          "value": 5,
          "unit": "km/h",
          "unitType": 7
        }
      },
      "precipitation": {
        "dbz": 0,
        "type": "SNOW"
      },
      "lightningCount": 0,
      "sunGlare": {
        "calculatedVehicleHeading": 36,
        "glareIndex": 0
      },
      "hazards": {
        "maxHazardIndex": 0
      },
      "notifications": []
    },
    {
      "iconCode": 35,
      "shortPhrase": "Partly cloudy",
      "isDayTime": false,
      "cloudCover": 46,
      "temperature": {
        "value": 2.4,
        "unit": "C",
        "unitType": 17
      },
      "wind": {
        "direction": {
          "degrees": 222
        },
        "speed": {
          "value": 4,
          "unit": "km/h",
          "unitType": 7
        }
      },
      "windGust": {
        "speed": {
          "value": 5,
          "unit": "km/h",
          "unitType": 7
        }
      },
      "precipitation": {
        "dbz": 0,
        "type": "SNOW"
      },
      "lightningCount": 0,
      "sunGlare": {
        "calculatedVehicleHeading": 38,
        "glareIndex": 0
      },
      "hazards": {
        "maxHazardIndex": 0
      },
      "notifications": []
    },
    {
      "iconCode": 35,
      "shortPhrase": "Partly cloudy",
      "isDayTime": false,
      "cloudCover": 39,
      "temperature": {
        "value": 2.3,
        "unit": "C",
        "unitType": 17
      },
      "wind": {
        "direction": {
          "degrees": 231
        },
        "speed": {
          "value": 4,
          "unit": "km/h",
          "unitType": 7
        }
      },
      "windGust": {
        "speed": {
          "value": 5,
          "unit": "km/h",
          "unitType": 7
        }
      },
      "precipitation": {
        "dbz": 0,
        "type": "SNOW"
      },
      "lightningCount": 0,
      "sunGlare": {
        "calculatedVehicleHeading": 43,
        "glareIndex": 0
      },
      "hazards": {
        "maxHazardIndex": 0
      },
      "notifications": []
    }
  ]
}

定義

名稱	Description
ErrorAdditionalInfo	資源管理錯誤其他資訊。
ErrorDetail	錯誤詳細數據。
ErrorResponse	錯誤回應
HazardDetail
HazardIndex	嚴重性/危險指數。 `0` - 無危險。 `1` - 了解情況，提高警覺。 `2` - 注意，做好準備。 `3` -下手。 `4` - 危及生命的緊急情況。
IconCode	表示顯示 `iconPhrase`. 有關詳細資訊，請參閱 Azure Maps 中的天氣服務。
JsonFormat	回應所需的格式。僅支援 `json` 格式。
SunGlare	一個評級，指示太陽對駕駛員的眩目程度。
UnitType	與所顯示的單位類型關聯的數位ID值。可用於單位轉換。有關詳細資訊，請參閱 Azure Maps 中的天氣服務。
WeatherAlongRoutePrecipitation	沿途天氣的降水預報。
WeatherAlongRouteResult	此物件是從成功的 Weather Along Route 返回的。
WeatherAlongRouteSummary	沿途天氣的簡短總結。
WeatherHazards	影響行程的天氣危險的描述。
WeatherNotification
WeatherUnit	與天氣相關的給定單位的特定值。
WeatherWaypoint
WindDetails	返回的風詳細資訊，包括速度和方向。
WindDirection	風向

ErrorAdditionalInfo

Object

資源管理錯誤其他資訊。

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

ErrorDetail

Object

錯誤詳細數據。

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

ErrorResponse

Object

錯誤回應

名稱	類型	Description
error	ErrorDetail	error 物件。

HazardDetail

Object

名稱類型 Description

hazardCode

string

每種災害類型的唯一標識符（不可顯示）：LightRain、ModerateRain、HeavyRain、LightMix、ModerateMix、HeavyMix、LightSnow、ModerateSnow、HeavySnow、LightIce、ModerateIce、HeavyIce、Hail、LargeHail、SunGlare、SunGlareHigh、Lightning、SevereLightning、WindModerate、WindHigh、WindExtreme、FloodWarning、FlashFloodWarning、TornadoWarning、TsunamiWarning、SevereThunderstormWarning。

hazardIndex

HazardIndex (int32)

嚴重性/危險指數。

0 - 無危險。
1 - 了解情況，提高警覺。
2 - 注意，做好準備。
3 -下手。
4 - 危及生命的緊急情況。

shortPhrase

string

描述預測條件和降水強度/類型的可顯示短語。

HazardIndex

列舉型別

嚴重性/危險指數。

0 - 無危險。
1 - 了解情況，提高警覺。
2 - 注意，做好準備。
3 -下手。
4 - 危及生命的緊急情況。

值	Description
0	無危險
1	了解情況
2	注意
3	採取行動
4	緊急狀況

IconCode

列舉型別

表示顯示 iconPhrase. 有關詳細資訊，請參閱 Azure Maps 中的天氣服務。

值	Description
1	晴朗
10
11	起霧
12	陣雨
13	多雲陣雨
14	晴時多雲陣雨
15	雷暴
16	多雲雷暴
17	局部多雲有雷陣雨
18	雨
19	陣雪
2	大部分晴朗
20	大部分多雲，伴隨零星小雪
21	晴時多雲陣雪
22	降雪
23	多雲降雪
24	冰
25	冰霰
26	凍雨
27
28
29	雨天降雪
3	晴時多雲
30	熱
31	冷
32	多風
33	晴
34	大部晴朗
35	局部多雲
36	間歇性雲（夜間）
37	朦朧月光
38	大部分時間多雲（夜間）
39	時陰陣雨
4	間歇雲量
40	大部分時間多雲，有陣雨（夜間）
41	部分多雲伴有雷暴
42	多雲，有雷暴（夜間）
43	大部分時間多雲，有陣雨（夜間）
44	大部分時間多雲，有雪（夜間）
5	和煦陽光
6	多雲
7	陰天
8	陰鬱 (陰天)
9

JsonFormat

列舉型別

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

值	Description
json	JavaScript 物件表示法數據交換格式

SunGlare

Object

一個評級，指示太陽對駕駛員的眩目程度。

名稱	類型	Description
calculatedVehicleHeading	integer (int32)	如果沒有為航點提供車輛航向值，則服務將根據相鄰航點的位置（如果提供）計算航向。
glareIndex	integer (int32)	一個從 0 到 100 的索引，表示駕駛員的太陽眩光強度。值 50 及以上可被視為對某些駕駛員構成危險，值 100 表示駕駛員直接駛向陽光，並且大氣條件清晰，允許太陽的全部強度使駕駛員失明。

UnitType

列舉型別

與所顯示的單位類型關聯的數位ID值。可用於單位轉換。有關詳細資訊，請參閱 Azure Maps 中的天氣服務。

值	Description
0	英呎
1	英吋
10	每秒公尺數
11	百帕
12	英吋汞柱
13	千帕
14	毫巴
15	毫米汞柱
16	磅力每平方英吋
17	攝氏
18	華氏
19	開爾文
2	英哩
20	百分比
21	浮動
22	整數
3	毫米
31	每立方米空氣中的微克數
4	釐米
5	公尺
6	公里
7	每小時公里數
8	節
9	英哩/小時

WeatherAlongRoutePrecipitation

Object

沿途天氣的降水預報。

名稱	類型	Description
dbz	number (double)	以 dBZ（相對於 Z 的分貝）為單位的預測降水強度，範圍從 0.0 到 100.0。
type	string	降水類型。如果出現降雨，則為：“RAIN”、“HAIL”、“SNOW”、“ICE”或“MIX”。

WeatherAlongRouteResult

Object

此物件是從成功的 Weather Along Route 返回的。

名稱	類型	Description
summary	WeatherAlongRouteSummary	沿途天氣的簡短總結。
waypoints	WeatherWaypoint[]	每個航點的數據按請求中指定的順序返回。

WeatherAlongRouteSummary

Object

沿途天氣的簡短總結。

名稱	類型	Description
hazards	WeatherHazards	影響行程的天氣危險的描述。
iconCode	IconCode (int32)	表示顯示 `iconPhrase`. 有關詳細資訊，請參閱 Azure Maps 中的天氣服務。

WeatherHazards

Object

影響行程的天氣危險的描述。

名稱類型 Description

hazardDetails

名稱	類型	Description
hazardDetails	HazardDetail[]	影響行程的天氣災害的詳細資訊。
maxHazardIndex	HazardIndex (int32)	嚴重性/危險指數。 `0` - 無危險。 `1` - 了解情況，提高警覺。 `2` - 注意，做好準備。 `3` -下手。 `4` - 危及生命的緊急情況。

HazardDetail[]

影響行程的天氣災害的詳細資訊。

maxHazardIndex

HazardIndex (int32)

嚴重性/危險指數。

0 - 無危險。
1 - 了解情況，提高警覺。
2 - 注意，做好準備。
3 -下手。
4 - 危及生命的緊急情況。

WeatherNotification

Object

名稱	類型	Description
hazardCode	string	每種災害類型的唯一標識符（不可顯示）：LightRain、ModerateRain、HeavyRain、LightMix、ModerateMix、HeavyMix、LightSnow、ModerateSnow、HeavySnow、LightIce、ModerateIce、HeavyIce、Hail、LargeHail、SunGlare、SunGlareHigh、Lightning、SevereLightning、WindModerate、WindHigh、WindExtreme、FloodWarning、FlashFloodWarning、TornadoWarning、TsunamiWarning、SevereThunderstormWarning。
hazardIndex	HazardIndex (int32)	嚴重性/危險指數。 `0` - 無危險。 `1` - 了解情況，提高警覺。 `2` - 注意，做好準備。 `3` -下手。 `4` - 危及生命的緊急情況。
shortPhrase	string	描述預測條件和降水強度/類型的可顯示短語。
type	string	一種通知類型，用於警告駕駛員危險的開始或危險強度的增加。

WeatherUnit

Object

與天氣相關的給定單位的特定值。

名稱	類型	Description
unit	string	返回值的單位類型。
unitType	UnitType (int32)	與所顯示的單位類型關聯的數位ID值。可用於單位轉換。有關詳細資訊，請參閱 Azure Maps 中的天氣服務。
value	number (float)	四捨五入的值。

WeatherWaypoint

Object

名稱	類型	Description
cloudCover	integer (int32)	表示雲覆蓋的百分比。
hazards	WeatherHazards	影響行程的天氣危險的描述。
iconCode	IconCode (int32)	表示顯示 `iconPhrase`. 有關詳細資訊，請參閱 Azure Maps 中的天氣服務。
isDayTime	boolean	指示一天中的時間。 True 表示“白天”，false 表示“夜晚”。
lightningCount	integer (int32)	開放尺度上的雷暴強度估計。值為 0 表示沒有雷暴;值為 1 或更高意味著雷暴強度越來越大。
notifications	WeatherNotification[]	天氣災害通知清單。
precipitation	WeatherAlongRoutePrecipitation	沿途天氣的降水預報。
shortPhrase	string	描述預測條件和降水強度/類型的可顯示短語。
sunGlare	SunGlare	一個評級，指示太陽對駕駛員的眩目程度。
temperature	WeatherUnit	與天氣相關的給定單位的特定值。
wind	WindDetails	返回的風詳細資訊，包括速度和方向。
windGust	WindDetails	返回的風詳細資訊，包括速度和方向。

WindDetails

Object

返回的風詳細資訊，包括速度和方向。

名稱	類型	Description
direction	WindDirection	風向
speed	WeatherUnit	以指定單位表示的風速。

WindDirection

Object

風向

名稱	類型	Description
degrees	integer (int32)	風向（方位角），從正北開始，繼續順時針方向。北方是0度，東是90度，南是180度，西部是270度。可能的值為 0-359。
localizedDescription	string	指定語言的 Direction 縮寫。

共用方式為

Weather - Get Weather Along Route

URI 參數

要求標頭

回應

安全性

AADToken

註釋

範圍

subscription-key

SAS Token

範例

Successfully retrieve detailed weather casts along a route described as a sequence of waypoints

範例要求

範例回覆

定義

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

HazardDetail

HazardIndex

IconCode

JsonFormat

SunGlare

UnitType

WeatherAlongRoutePrecipitation

WeatherAlongRouteResult

WeatherAlongRouteSummary

WeatherHazards

WeatherNotification

WeatherUnit

WeatherWaypoint

WindDetails

WindDirection