Weather - Get Weather Along Route

參考

服務:: Maps

API 版本:: 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}

含選擇性參數:

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 專案標識碼安全性，請參閱下列文章以取得指引。

回應

名稱	類型	Description
200 OK	WeatherAlongRouteResult	確定
Other Status Codes	ErrorResponse	發生意外錯誤。

安全性

AADToken

這些是 Microsoft Entra OAuth 2.0 流程。與 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 入口網站中建立 Azure 地圖服務帳戶或使用 PowerShell、CLI、Azure SDK 或 REST API 時所佈建的共用密鑰。

使用此金鑰，任何應用程式都可以存取所有 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 地圖服務中的天氣服務。
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	error 物件。

HazardDetail

名稱類型 Description

hazardCode

string

每種危險類型的唯一標識符 (不可顯示) ：LightRain、 ModerateRain、HeavyRain、LightMix、ModerateMix、HeavyMix、LightSnow、ModerateSnow、LightIce、ModerateIce、HeavyIce、HeavyIce、LargeHail、SunGlare、SunGlareHigh、Lightning、HeavyLightning、WindModerate、WindHigh、WindExtreme、FloodWarning、FlashFloodWarning、TornadoWarning、InitializeWarning、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	相對於 0.0 到 100.0 的 Z) ，dBZ 中的預測濕度 (減數。
type	string	雪地類型。如果應該發生雨，則其類型為：“RAIN”、“SNOW”、“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、HeavyIce、LargeHail、SunGlare、SunGlareHigh、Lightning、HeavyLightning、WindModerate、WindHigh、WindExtreme、FloodWarning、FlashFloodWarning、TornadoWarning、InitializeWarning、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

備註

範圍

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

其他資源