Weather - Get Minute Forecast

用於獲取未來 120 分鐘的每分鐘預報,間隔為 1 分鐘、5 分鐘和 15 分鐘。
該 Get Minute Forecast API 是一個 HTTP GET 請求,用於返回給定位置未來 120 分鐘的每分鐘預測。 使用者可以以 1、5 和 15 分鐘的間隔要求氣象預報。 回應將包括降水類型(包括雨、雪或兩者的混合物)、開始時間和降水強度值 (dBZ) 等詳細資訊。 有關更多資訊,請參閱請求每分鐘 天氣預報數據。

GET {endpoint}/weather/forecast/minute/json?api-version=1.1&query={query}
GET {endpoint}/weather/forecast/minute/json?api-version=1.1&query={query}&interval={interval}&language={language}

URI 參數

名稱 位於 必要 類型 Description
endpoint
path True

string (uri)

Azure 地圖服務 服務的主機名稱。 Azure公有雲用 https://atlas.microsoft.com。 若要鎖定特定Azure 地圖服務地理或主權雲,請參見 Azure 地圖服務 地理範圍。

format
path True

JsonFormat

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

api-version
query True

string

minLength: 1

用於此作業的 API 版本。

query
query True

number[]

指定為逗號分隔字串的適用查詢,由緯度所組成,後面接著經度,例如 “47.641268,-122.125679”。

通常,天氣資訊適用於陸地上的位置、被陸地包圍的水體以及距離海岸線約 50 海裡以內的海洋區域。

interval
query

integer (int32)

指定返回的天氣預報的時間間隔(以分鐘為單位)。 支援的值包括

  • 1 - 檢索 1 分鐘間隔的預測。 預設會傳回 。
  • 5 - 檢索 5 分鐘間隔的預測。
  • 15 - 檢索每 15 分鐘的預測。
language
query

string

應該傳回搜尋結果的語言。 應該是其中一個支援的 IETF 語言標記,不區分大小寫。 當特定欄位無法使用指定語言的數據時,會使用預設語言。

如需詳細資訊,請參閱 支援的語言。

要求標頭

名稱 必要 類型 Description
x-ms-client-id

string

表示該帳號用於 Microsoft Entra ID 安全模型。 這個Azure 地圖服務帳號的唯一 ID 可以從 Azure 地圖服務 管理平面的 Account API 取得。 欲了解更多在Azure 地圖服務中使用Microsoft Entra ID安全,請參見管理 Azure 地圖服務 認證。

回覆

名稱 類型 Description
200 OK

MinuteForecastResult

要求已成功。

Other Status Codes

ErrorResponse

未預期的錯誤回應。

安全性

AadToken

這些是Microsoft Entra OAuth 2.0流。 當與 Azure 基於角色的存取 控制結合時,可以用來控制對 Azure 地圖服務 REST API 的存取。 Azure 角色基礎存取控制用於指定對一個或多個 Azure 地圖服務 資源帳號或子資源的存取權限。 任何使用者、群組或服務主體都可以透過內建角色或由一或多個 Azure 地圖服務 REST API 許可權所組成的自定義角色來授與存取權。

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

Note

  • 此安全性定義 需要 使用 x-ms-client-id 標頭來指出應用程式要求存取的 Azure 地圖服務資源。 這可以從 地圖管理 API取得。
  • Authorization URL 專屬於 Azure 公用雲端實例。 主權雲擁有獨特的授權網址和 Microsoft Entra ID 設定。
  • Azure 角色型訪問控制是從 azure 管理平面 設定, 透過 Azure 入口網站、PowerShell、CLI、Azure SDK 或 REST API。
  • Azure 地圖服務 Web SDK 的使用,可讓您針對多個使用案例設定應用程式。
  • 如需Microsoft身分識別平臺的詳細資訊,請參閱 Microsoft 身分識別平臺概觀。

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

範圍

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

subscription-key

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

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

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

類型: apiKey
位於: header

SAS Token

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

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

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

類型: apiKey
位於: header

範例

Successfully retrieve minute-by-minute forecasts for a given location

範例要求

GET https://atlas.microsoft.com/weather/forecast/minute/json?api-version=1.1&query=47.632346,-122.138874&interval=15

範例回覆

{
  "intervalSummaries": [
    {
      "briefPhrase": "Rain ending in %minute_value min",
      "endMinute": 24,
      "iconCode": 12,
      "longPhrase": "Rain ending in %minute_value min",
      "shortPhrase": "Rain ending in %minute_value min",
      "startMinute": 0,
      "totalMinutes": 25
    },
    {
      "briefPhrase": "No precipitation for at least %MINUTE_VALUE min",
      "endMinute": 119,
      "iconCode": 7,
      "longPhrase": "No precipitation for at least %MINUTE_VALUE min",
      "shortPhrase": "No precip for %MINUTE_VALUE min",
      "startMinute": 25,
      "totalMinutes": 95
    }
  ],
  "intervals": [
    {
      "cloudCover": 100,
      "color": {
        "blue": 2,
        "green": 98,
        "hex": "#086202",
        "red": 8
      },
      "dbz": 23,
      "iconCode": 12,
      "minute": 0,
      "precipitationType": "Rain",
      "shortPhrase": "Light Rain",
      "simplifiedColor": {
        "blue": 39,
        "green": 190,
        "hex": "#23BE27",
        "red": 35
      },
      "startTime": "2019-11-14T15:18:00-08:00",
      "threshold": "LIGHT"
    },
    {
      "cloudCover": 100,
      "color": {
        "blue": 9,
        "green": 133,
        "hex": "#208509",
        "red": 32
      },
      "dbz": 18,
      "iconCode": 12,
      "minute": 15,
      "precipitationType": "Rain",
      "shortPhrase": "Light Rain",
      "simplifiedColor": {
        "blue": 39,
        "green": 190,
        "hex": "#23BE27",
        "red": 35
      },
      "startTime": "2019-11-14T15:33:00-08:00",
      "threshold": "LIGHT"
    },
    {
      "cloudCover": 100,
      "dbz": 0,
      "iconCode": 7,
      "minute": 30,
      "shortPhrase": "No Precipitation",
      "startTime": "2019-11-14T15:48:00-08:00"
    },
    {
      "cloudCover": 100,
      "dbz": 0,
      "iconCode": 7,
      "minute": 45,
      "shortPhrase": "No Precipitation",
      "startTime": "2019-11-14T16:03:00-08:00"
    },
    {
      "cloudCover": 100,
      "dbz": 0,
      "iconCode": 7,
      "minute": 60,
      "shortPhrase": "No Precipitation",
      "startTime": "2019-11-14T16:18:00-08:00"
    },
    {
      "cloudCover": 100,
      "dbz": 0,
      "iconCode": 7,
      "minute": 75,
      "shortPhrase": "No Precipitation",
      "startTime": "2019-11-14T16:33:00-08:00"
    },
    {
      "cloudCover": 100,
      "dbz": 0,
      "iconCode": 7,
      "minute": 90,
      "shortPhrase": "No Precipitation",
      "startTime": "2019-11-14T16:48:00-08:00"
    },
    {
      "cloudCover": 100,
      "dbz": 0,
      "iconCode": 7,
      "minute": 105,
      "shortPhrase": "No Precipitation",
      "startTime": "2019-11-14T17:03:00-08:00"
    }
  ],
  "summary": {
    "briefPhrase": "Rain ending in 25 min",
    "briefPhrase60": "Rain ending in 25 min",
    "iconCode": 12,
    "longPhrase": "Rain ending in 25 min",
    "shortPhrase": "Rain ending in 25 min"
  }
}

定義

名稱 Description
ColorValue

RGB 顏色,以分量(,redgreen , blue) 和十六進位(hex) 兩種形式回傳。 用於分分鐘預報,將每個區間渲染成雷達式顯示器——詳見 ForecastInterval.color 映射到 dbz的全光譜色彩,以及 ForecastInterval.simplifiedColor 由 precipitationType 和 threshold衍生出的較粗色。 關於底層的色彩映射,請參見 Azure 地圖服務 中的天氣服務。

ErrorAdditionalInfo

資源管理錯誤其他資訊。

ErrorDetail

錯誤詳細數據。

ErrorResponse

所有 Azure Resource Manager API 的常見錯誤回應,用於回傳失敗操作的錯誤細節。 (這也遵循 OData 錯誤回應格式。)。

ForecastInterval

代表分分鐘預報中的單一時間切片,描述該區間內預期的天氣狀況。 每個區間涵蓋1、5或15分鐘——視所要求的解析度而定——並包含開始時間、降水強度()、dbz降水類型與閾值、簡短描述短語、圖示代碼、雲量覆蓋,以及用於雷達式顯示器上視覺化條件的全光譜與簡化色彩。

IconCode

數字天氣條件代碼,用來標示要顯示哪個圖示。 此列舉中的每個值對應一個 Azure 地圖服務 天氣圖示(如晴天、陰天或雷雨),並與一個人類可iconPhrase讀的回報一對應。 相同的程式碼可以出現在當前、每小時、每日、季度及每分鐘的回應中,讓應用程式能在所有氣象服務中呈現一致的圖示。

關於完整的代碼清單、它們所對應的圖示以及範例影像,請參見 Azure 地圖服務 中的天氣服務。

IntervalSummary

描述連續時段的天氣展望,包含分分鐘預報中——通常是一段類似條件的連續期,例如 25分鐘後結束的雨 或 10分鐘後開始的輕雪。 每個摘要都指定從預報開始startMinute(、 endMinute、 totalMinutes)起計分鐘的視窗,提供三種長度的短語描述(短、簡、長),以便依據可用 UI 空間顯示適當的細節,並包含 iconCode 代表性天氣圖示。 A MinuteForecastResult 回傳一個或多個 IntervalSummary 項目,這些項目合計涵蓋了預測期間。

JsonFormat

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

MinuteForecastResult

回應由「取得分鐘預報」操作回傳,提供指定地點未來120分鐘內的逐分鐘降水展望,並以所求解析度(1、5或15分鐘)呈現。 回應分為三層:包含短語描述及代表性圖示的整體 summary 圖示; intervalSummaries 一個將連續分鐘分組成較長段相似條件(如 25 分鐘結束的雨);以及 intervals 包含詳細每分鐘預報點的陣列,包括降水強度(dbz)、降水類型、雲量及雷達風格視覺化所用顏色。

MinuteForecastSummary

提供短語摘要,描述即將到來的逐分鐘預報期的降水展望。 包含多種短語長度——短短(~25 字元)、簡短(~60 字元)及長短(60+ 字元)——讓應用程式能依照可用介面空間顯示最細緻的細節。 A iconCode 代表該時期的天氣圖示。

PrecipitationType

指定降水類型。 有效的數 值有雨、 雪、 冰或 混合。 當 dBZ 大於零時,此屬性包含在回應中。

ColorValue

RGB 顏色,以分量(,redgreen , blue) 和十六進位(hex) 兩種形式回傳。 用於分分鐘預報,將每個區間渲染成雷達式顯示器——詳見 ForecastInterval.color 映射到 dbz的全光譜色彩,以及 ForecastInterval.simplifiedColor 由 precipitationType 和 threshold衍生出的較粗色。 關於底層的色彩映射,請參見 Azure 地圖服務 中的天氣服務。

名稱 類型 Description
blue

integer (int32)

RGB 值的藍色分量。 有效數值範圍為 0 到 255。

green

integer (int32)

RGB 值的綠色分量。 有效數值範圍為 0 到 255。

hex

string

顏色與帶有前綴 # 的十六進位 RGB 字串相同——例如,紅色的 #FF0000 。

red

integer (int32)

RGB 值的紅色分量。 有效數值範圍為 0 到 255。

ErrorAdditionalInfo

資源管理錯誤其他資訊。

名稱 類型 Description
info

其他資訊。

type

string

其他信息類型。

ErrorDetail

錯誤詳細數據。

名稱 類型 Description
additionalInfo

ErrorAdditionalInfo[]

錯誤其他資訊。

code

string

錯誤碼。

details

ErrorDetail[]

錯誤詳情

message

string

錯誤訊息。

target

string

錯誤目標。

ErrorResponse

所有 Azure Resource Manager API 的常見錯誤回應,用於回傳失敗操作的錯誤細節。 (這也遵循 OData 錯誤回應格式。)。

名稱 類型 Description
error

ErrorDetail

error 物件。

ForecastInterval

代表分分鐘預報中的單一時間切片,描述該區間內預期的天氣狀況。 每個區間涵蓋1、5或15分鐘——視所要求的解析度而定——並包含開始時間、降水強度()、dbz降水類型與閾值、簡短描述短語、圖示代碼、雲量覆蓋,以及用於雷達式顯示器上視覺化條件的全光譜與簡化色彩。

名稱 類型 Description
cloudCover

integer (int32)

此期間天空被雲覆蓋的百分比,從0(晴朗)到100(陰天)不等。 可能是 NULL。

color

ColorValue

映射到 dbz的全光譜色彩用於在雷達式顯示器上渲染此區間。 只有當 大於零時 dbz 才會回傳。

dbz

number (double)

雷達反射率(dBZ)相對於 Z 的分貝預測,作為降水強度的衡量指標。 數值越高表示降水量越多;值為0則表示無降水。

iconCode

IconCode

此時段的代表性天氣圖示代碼。 該數值對應於 Azure 地圖服務 的天氣圖示——完整列表請參見 Azure 地圖服務 中的天氣服務。

minute

integer (int32)

此預報區間的起始時間表示為預報開始(分鐘0)起的分鐘數。 與對應的場配對 startTime ,並匹配 startMinute 對應 IntervalSummary的場。

precipitationType

PrecipitationType

預期降水類型為 雨、 雪、 冰或 混合型。 只有當 大於零時 dbz 才會回傳。

shortPhrase

string

一段描述此期間降水狀況的短語(例如, 輕雨)。 最多可達約25個字元。

simplifiedColor

ColorValue

一種簡化的顏色,源自 precipitationType 和 threshold,適合需要快速且易讀雷達視覺化而非完整 dBZ 色譜的使用者介面。 只有當 大於零時 dbz 才會回傳。

startTime

string (date-time)

此預報區間的開始,格式為 RFCyyyy-mm-ddThh:mm:ss±hh:mm3339 ()。 例如, 2019-11-14T15:18:00-08:00。

threshold

string

降水 precipitationType 落入的強度分類, 例如輕度、 中度或 重度。 使用 來 precipitationType 確定 simplifiedColor。 只有當 大於零時 dbz 才會回傳。

IconCode

數字天氣條件代碼,用來標示要顯示哪個圖示。 此列舉中的每個值對應一個 Azure 地圖服務 天氣圖示(如晴天、陰天或雷雨),並與一個人類可iconPhrase讀的回報一對應。 相同的程式碼可以出現在當前、每小時、每日、季度及每分鐘的回應中,讓應用程式能在所有氣象服務中呈現一致的圖示。

關於完整的代碼清單、它們所對應的圖示以及範例影像,請參見 Azure 地圖服務 中的天氣服務。

值 Description
1

Sunny

2

大部分晴朗

3

晴時多雲

4

間歇雲量

5

和煦陽光

6

多雲

7

Cloudy

8

陰鬱 (陰天)

11

Fog

12

Showers

13

多雲陣雨

14

晴時多雲陣雨

15

Thunderstorms

16

多雲雷暴

17

局部多雲有雷陣雨

18

Rain

19

Flurries

20

大部分多雲,伴隨零星小雪

21

晴時多雲陣雪

22

Snow

23

多雲降雪

24

Ice

25

Sleet

26

凍雨

29

雨天降雪

30

Hot

31

Cold

32

Windy

33

晴

34

大部晴朗

35

局部多雲

36

間歇雲量

37

朦朧月光

38

多雲

39

時陰陣雨

40

多雲陣雨

41

部分多雲伴有雷暴

42

多雲雷暴

43

大部分多雲,伴隨零星小雪

44

多雲降雪

IntervalSummary

描述連續時段的天氣展望,包含分分鐘預報中——通常是一段類似條件的連續期,例如 25分鐘後結束的雨 或 10分鐘後開始的輕雪。 每個摘要都指定從預報開始startMinute(、 endMinute、 totalMinutes)起計分鐘的視窗,提供三種長度的短語描述(短、簡、長),以便依據可用 UI 空間顯示適當的細節,並包含 iconCode 代表性天氣圖示。 A MinuteForecastResult 回傳一個或多個 IntervalSummary 項目,這些項目合計涵蓋了預測期間。

名稱 類型 Description
briefPhrase

string

簡短描述此期間降水狀況的短語。 最多可達60字元。

endMinute

integer (int32)

此區間的最後一分鐘,表示為預報開始(第0分鐘)起的分鐘數。

iconCode

IconCode

此時段的代表性天氣圖示代碼。 該數值對應於 Azure 地圖服務 的天氣圖示——完整列表請參見 Azure 地圖服務 中的天氣服務。

longPhrase

string

一段長短描述此期間的降水狀況。 支援超過 60 個角色。

shortPhrase

string

一段描述此期間降水狀況的簡短短語。 最多可達25個字元。

startMinute

integer (int32)

此區間的第一分鐘,表示為預報開始(第0分鐘)起的分鐘數。

totalMinutes

integer (int32)

此間隔長度,以分鐘為單位endMinute - startMinute ( + 1)。

JsonFormat

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

值 Description
json

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

MinuteForecastResult

回應由「取得分鐘預報」操作回傳,提供指定地點未來120分鐘內的逐分鐘降水展望,並以所求解析度(1、5或15分鐘)呈現。 回應分為三層:包含短語描述及代表性圖示的整體 summary 圖示; intervalSummaries 一個將連續分鐘分組成較長段相似條件(如 25 分鐘結束的雨);以及 intervals 包含詳細每分鐘預報點的陣列,包括降水強度(dbz)、降水類型、雲量及雷達風格視覺化所用顏色。

名稱 類型 Description
intervalSummaries

IntervalSummary[]

短語摘要將預報視窗劃分為一段或多段相連的相似條件段——例如, 雨後25分鐘結束 ,接著是 局部多雲。 每個條目都指定涵蓋的分鐘數(startMinute, , endMinutetotalMinutes),提供短短、短短及長句變體,並包含iconCode一段長度。 這些摘要涵蓋了整個預報期間。

intervals

ForecastInterval[]

詳細的每步預測點組成了分分鐘的預報。 每個 ForecastInterval 顯示時長為1、5或15分鐘——視所要求解析度而定——並報告開始時間、降水強度()、dbz降水類型與閾值、簡短描述短語、圖示代碼、雲層覆蓋,以及用於渲染雷達式顯示器的顏色。

summary

MinuteForecastSummary

頂層短語摘要,描述整個約120分鐘預報期間的降水展望。 包含短、短、長三種變體,以便依據可用介面空間顯示適當的細節,並代表 iconCode 該時期。

MinuteForecastSummary

提供短語摘要,描述即將到來的逐分鐘預報期的降水展望。 包含多種短語長度——短短(~25 字元)、簡短(~60 字元)及長短(60+ 字元)——讓應用程式能依照可用介面空間顯示最細緻的細節。 A iconCode 代表該時期的天氣圖示。

名稱 類型 Description
briefPhrase

string

簡短描述整個約120分鐘預報窗口內的降水展望。 最多可達約60字元。

briefPhrase60

string

這是一段簡短的短語,僅描述接下來60分鐘的降水展望(比本天體其他短語短)。 最多可達約60字元。

iconCode

IconCode

代表整個 ~120 分鐘預報視窗的天氣圖示代碼。 該數值對應於 Azure 地圖服務 的天氣圖示——完整列表請參見 Azure 地圖服務 中的天氣服務。

longPhrase

string

一段長短語描述整個約120分鐘預報窗口的降水展望。 支援超過 60 個角色。

shortPhrase

string

一段簡短的短語,描述整個約120分鐘預報窗口的降水展望。 最多可達約25個字元。

PrecipitationType

指定降水類型。 有效的數 值有雨、 雪、 冰或 混合。 當 dBZ 大於零時,此屬性包含在回應中。

值 Description
Ice

Ice

Mix

Mix

Rain

Rain

Snow

Snow