Weather - Get Weather Along Route

參考

Service:: Maps

API Version:: 1.1

使用來取得位置精確、最新的預測，其中包含路線上的天氣危險評量和通知。

Get Weather Along Route API 是一項 HTTP GET 要求，會傳回超本機 (一或更少) 、即時天氣現在廣播、天氣危險評量，以及路線描述為一連串路線的通知。這包括影響路點或路線的天氣危險清單，以及每個路線的匯總危險索引，可用來根據驅動程式的安全程度來繪製路線的每個部分。提交路點時，建議在120分鐘或不久後停留在或接近的距離內。數據會每隔五分鐘更新一次。

此服務會補充 Azure 地圖服務路由服務，可讓您先要求來源與目的地之間的路線，並使用該路由作為天氣沿著路線端點的輸入。

此外，此服務也支持針對遇到天氣危險強度增加的路點產生天氣通知的案例。例如，如果車輛預期在到達路點時開始發生暴雨，則會針對該路點產生天氣通知，讓最終產品在駕駛到達該路點之前顯示暴雨通知。例如，在地理柵欄上或可選取的距離上，顯示導航點通知的觸發程式。

此 API 涵蓋行星的所有區域，但綠色蘭和北極陸上方的緯度除外。

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

With optional parameters:

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 個導航點。 waypoint 表示位置、ETA 和選擇性標題：緯度、經度、ETA、標題，其中 `Latitude` - 以十進制度表示的緯度座標。 `Longitude` - 十進位數的經度座標。 `ETA (estimated time of arrival)` - 從車輛到達路線點所花費的目前時間的分鐘數。允許的範圍是從 0.0 到 120.0 分鐘。 `Heading` - 選擇性值，指出通過路線點的車輛標題。以相對於 true north 的順時針度表示。這是為了計算太陽光作為駕駛危險而發出。允許的範圍是從 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

這些是 OAuth 2.0 流程 Microsoft Entra。與 Azure 角色型存取控制配對時，可用來控制對 #D11BB6D11F568471295A61798399F3BC4 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 身分識別平台概觀。

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

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

subscription-key

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

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

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

Type: apiKey
In: query

SAS Token

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

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

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

Type: apiKey
In: header

範例

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

Sample Request

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

Sample Response

Status code:: 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 地圖服務中的天氣服務。
JsonFormat	所需的回應格式。僅支援 `json` 格式。
SunGlare	一個評等，指出驅策因素的太陽如何盲目。
UnitType	與所顯示單位類型相關聯的數值標識碼。可用於單元翻譯。如需詳細資訊，請參閱 Azure 地圖服務中的天氣服務。
WeatherAlongRoutePrecipitation	路線上天氣的氣象預報。
WeatherAlongRouteResult	此物件會從成功的天氣沿著路線傳回。
WeatherAlongRouteSummary	路線天氣的簡短摘要。
WeatherHazards	影響車程的天氣危險描述。
WeatherNotification
WeatherUnit	與天氣相關的指定單位特定值。
WeatherWaypoint
WindDetails	傳回的風力詳細數據包括速度和方向。
WindDirection	風向

ErrorAdditionalInfo

資源管理錯誤其他資訊。

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

ErrorDetail

錯誤詳細數據。

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

ErrorResponse

錯誤回應

名稱	類型	Description
error	ErrorDetail	錯誤物件。

HazardDetail

名稱類型 Description

hazardCode

string

每種危險類型的唯一標識符 (不可顯示) ：LightRain、 ModerateRain、HeavyRain、LightMix、ModerateMix、HeavyMix、LightSnow、ModerateSnow、LightIce、ModerateIce、HeavyIce、LargeHail、SunGlare、SunGlare、SunGlareHigh、Lightning、HeavyLightning、WindModerate、WindHigh、WindExtreme、FloodWarning、FlashFloodWarning、TornadoWarning、SystemWarning、HeavyThunderstormWarning。

hazardIndex

HazardIndex

嚴重性/危險索引。

0 - 沒有危險。
1 - 通知，請注意。
2 - 請留意，請做好準備。
3 - 採取動作。
4 - 生命威脅，緊急。

shortPhrase

string

描述預測條件和濃度/類型的可顯示簡短片語。

HazardIndex

嚴重性/危險索引。

0 - 沒有危險。
1 - 通知，請注意。
2 - 請留意，請做好準備。
3 - 採取動作。
4 - 生命威脅，緊急。

名稱	類型	Description
0	Integer
1	Integer
2	Integer
3	Integer
4	Integer

IconCode

數值，表示顯示的 iconPhrase影像。如需詳細資訊，請參閱 Azure 地圖服務中的天氣服務。

名稱	類型	Description
1	Integer
10	Integer
11	Integer
12	Integer
13	Integer
14	Integer
15	Integer
16	Integer
17	Integer
18	Integer
19	Integer
2	Integer
20	Integer
21	Integer
22	Integer
23	Integer
24	Integer
25	Integer
26	Integer
27	Integer
28	Integer
29	Integer
3	Integer
30	Integer
31	Integer
32	Integer
33	Integer
34	Integer
35	Integer
36	Integer
37	Integer
38	Integer
39	Integer
4	Integer
40	Integer
41	Integer
42	Integer
43	Integer
44	Integer
5	Integer
6	Integer
7	Integer
8	Integer
9	Integer

JsonFormat

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

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

SunGlare

一個評等，指出驅策因素的太陽如何盲目。

名稱	類型	Description
calculatedVehicleHeading	integer	如果未提供路線點的車輛標題值，則服務會根據鄰近路點的位置來計算標題。
glareIndex	integer	從 0 到 100 的索引，表示驅動程式的太陽光濃度。值 50 和更新版本可視為某些驅動程式的危險，而值為 100 表示駕駛直接進入太陽，而氣象條件清楚允許完全的太陽濃度使驅動程式盲目。

UnitType

與所顯示單位類型相關聯的數值標識碼。可用於單元翻譯。如需詳細資訊，請參閱 Azure 地圖服務中的天氣服務。

名稱	類型	Description
0	Integer
1	Integer
10	Integer
11	Integer
12	Integer
13	Integer
14	Integer
15	Integer
16	Integer
17	Integer
18	Integer
19	Integer
2	Integer
20	Integer
21	Integer
22	Integer
3	Integer
31	Integer
4	Integer
5	Integer
6	Integer
7	Integer
8	Integer
9	Integer

WeatherAlongRoutePrecipitation

路線上天氣的氣象預報。

名稱	類型	Description
dbz	number	dBZ (從0.0到100.0的 Z) 的預測濕度。
type	string	雪地類型。如果應該發生氣候，其類型會是：“RAIN”、“RAIN”、“SNOW”、“ICE” 或 “MIX”。

WeatherAlongRouteResult

此物件會從成功的天氣沿著路線傳回。

名稱	類型	Description
summary	WeatherAlongRouteSummary	路線天氣的簡短摘要。
waypoints	WeatherWaypoint[]	每個傳回方式點的數據，順序與要求中指定的順序相同。

WeatherAlongRouteSummary

路線天氣的簡短摘要。

名稱	類型	Description
hazards	WeatherHazards	影響車程的天氣危險描述。
iconCode	IconCode	數值，表示顯示的 `iconPhrase`影像。如需詳細資訊，請參閱 Azure 地圖服務中的天氣服務。

WeatherHazards

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

名稱類型 Description

hazardDetails

名稱	類型	Description
hazardDetails	HazardDetail[]	影響車程的天氣危險詳細數據。
maxHazardIndex	HazardIndex	嚴重性/危險索引。 `0` - 沒有危險。 `1` - 通知，請注意。 `2` - 請留意，請做好準備。 `3` - 採取動作。 `4` - 生命威脅，緊急。

HazardDetail[]

影響車程的天氣危險詳細數據。

maxHazardIndex

HazardIndex

嚴重性/危險索引。

0 - 沒有危險。
1 - 通知，請注意。
2 - 請留意，請做好準備。
3 - 採取動作。
4 - 生命威脅，緊急。

WeatherNotification

名稱	類型	Description
hazardCode	string	每種危險類型的唯一標識符 (不可顯示) ：LightRain、 ModerateRain、HeavyRain、LightMix、ModerateMix、HeavyMix、LightSnow、ModerateSnow、LightIce、ModerateIce、HeavyIce、LargeHail、SunGlare、SunGlare、SunGlareHigh、Lightning、HeavyLightning、WindModerate、WindHigh、WindExtreme、FloodWarning、FlashFloodWarning、TornadoWarning、SystemWarning、HeavyThunderstormWarning。
hazardIndex	HazardIndex	嚴重性/危險索引。 `0` - 沒有危險。 `1` - 通知，請注意。 `2` - 請留意，請做好準備。 `3` - 採取動作。 `4` - 生命威脅，緊急。
shortPhrase	string	描述預測條件和濃度/類型的可顯示簡短片語。
type	string	產生一種通知，用來警告危險威脅的驅策因素，或增加危險強度。

WeatherUnit

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

名稱	類型	Description
unit	string	傳回值的單位類型。
unitType	UnitType	與所顯示單位類型相關聯的數值標識碼。可用於單元翻譯。如需詳細資訊，請參閱 Azure 地圖服務中的天氣服務。
value	number	捨入值。

WeatherWaypoint

名稱	類型	Description
cloudCover	integer	代表雲端涵蓋的百分比。
hazards	WeatherHazards	影響車程的天氣危險描述。
iconCode	IconCode	數值，表示顯示的 `iconPhrase`影像。如需詳細資訊，請參閱 Azure 地圖服務中的天氣服務。
isDayTime	boolean	表示一天的時間。 True 表示 'day'，'，false 表示 'night' 。
lightningCount	integer	在開放式刻度上估計暴風雨強度。值為 0 表示沒有暴雨;1 和更高的值表示增加濃度有一個暴雨。
notifications	WeatherNotification[]	天氣危險通知的清單。
precipitation	WeatherAlongRoutePrecipitation	路線上天氣的氣象預報。
shortPhrase	string	描述預測條件和濃度/類型的可顯示簡短片語。
sunGlare	SunGlare	一個評等，指出驅策因素的太陽如何盲目。
temperature	WeatherUnit	與天氣相關的指定單位特定值。
wind	WindDetails	傳回的風力詳細數據包括速度和方向。
windGust	WindDetails	傳回的風力詳細數據包括速度和方向。

WindDetails

傳回的風力詳細數據包括速度和方向。

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

WindDirection

風向

名稱	類型	Description
degrees	integer	Azimuth 度的風向，從 true North 開始，並繼續順時針方向。北為 0 度，東部為 90 度，南為 180 度，西部為 270 度。可能的值 0-359。
localizedDescription	string	指定語言的方向縮寫。

Weather - Get Weather Along Route

URI 參數

要求標頭

回應

安全性

AADToken

備註

Scopes

subscription-key

SAS Token

範例

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

Sample Request

Sample Response

定義

ErrorAdditionalInfo

ErrorDetail

ErrorResponse

HazardDetail

HazardIndex

IconCode

JsonFormat

SunGlare

UnitType

WeatherAlongRoutePrecipitation

WeatherAlongRouteResult

WeatherAlongRouteSummary

WeatherHazards

WeatherNotification

WeatherUnit

WeatherWaypoint

WindDetails

WindDirection

其他資源