Weather - Get Current Air Quality

用於獲取當前空氣質量資訊,包括潛在風險和建議的預防措施。
API Get Current Air Quality 是一個 HTTP GET 請求,它返回有關污染物濃度和當前空氣質量總體狀態的詳細資訊,包括污染水準、空氣品質指數值、主要污染物,以及總結風險級別和建議預防措施的簡短聲明。

GET {endpoint}/weather/airQuality/current/json?api-version=1.1&query={query}
GET {endpoint}/weather/airQuality/current/json?api-version=1.1&language={language}&query={query}&pollutants={pollutants}

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 海裡以內的海洋區域。

language
query

string

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

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

pollutants
query

boolean

返回有關每種污染物的詳細信息的布爾值。 默認情況下為 True。

要求標頭

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

string

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

回覆

名稱 類型 Description
200 OK

AirQualityResult

要求已成功。

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

範例

Get Current Air Quality

範例要求

GET https://atlas.microsoft.com/weather/airQuality/current/json?api-version=1.1&query=47.632346,-122.13887

範例回覆

{
  "results": [
    {
      "description": "The air quality is generally acceptable for most individuals. However, sensitive groups may experience minor to moderate symptoms from long-term exposure.",
      "category": "Fair",
      "categoryColor": "#FFC300",
      "dateTime": "2021-07-19T02:00:00+00:00",
      "dominantPollutant": "Ozone",
      "globalIndex": 22.1,
      "index": 21.6,
      "pollutants": [
        {
          "name": "Nitrogen Dioxide",
          "type": "NO2",
          "concentration": {
            "unit": "µg/m³",
            "unitType": 31,
            "value": 13.4
          },
          "globalIndex": 6.7,
          "index": 6.7
        },
        {
          "name": "Ozone",
          "type": "O3",
          "concentration": {
            "unit": "µg/m³",
            "unitType": 31,
            "value": 53.5
          },
          "globalIndex": 22.1,
          "index": 21.6
        },
        {
          "name": "Particulate Matter 10",
          "type": "PM10",
          "concentration": {
            "unit": "µg/m³",
            "unitType": 31,
            "value": 12.2
          },
          "globalIndex": 12.2,
          "index": 11.3
        },
        {
          "name": "Particulate Matter 2.5",
          "type": "PM2.5",
          "concentration": {
            "unit": "µg/m³",
            "unitType": 31,
            "value": 3.2
          },
          "globalIndex": 6.5,
          "index": 13.5
        },
        {
          "name": "Carbon Monoxide",
          "type": "CO",
          "concentration": {
            "unit": "µg/m³",
            "unitType": 31,
            "value": 118.4
          },
          "globalIndex": 0.6,
          "index": 1.2
        },
        {
          "name": "Sulfur Dioxide",
          "type": "SO2",
          "concentration": {
            "unit": "µg/m³",
            "unitType": 31,
            "value": 1.1
          },
          "globalIndex": 1.1,
          "index": 0.6
        }
      ]
    }
  ]
}

定義

名稱 Description
AirQuality

某一地點的當前空氣品質讀數,則以 的 AirQualityResult.results條目返回。 結合當地監管機構報告的空氣品質指數(index)與國際標準化指數(globalIndex),識別 dominantPollutant 結果驅動因素,並與適合色彩編碼介面的本地定性 category 及匹配 categoryColor 配對。 短片 description 說明該讀數對日常活動及健康注意事項的意義,當請求要求污染物細節時, pollutants 陣列會呈現每項污染物的分解。

AirQualityResult

回應由「取得當前空氣品質」操作回傳,提供指定地點的當前空氣品質狀況。 陣 results 列包含一個 AirQuality 條目,總結本地及全球標準化的空氣品質指數、主要污染物、質性分類及匹配顏色、健康影響的簡短描述,以及(如有需求)各污染物細節。

DominantPollutant

識別濃度最高的污染物。

ErrorAdditionalInfo

資源管理錯誤其他資訊。

ErrorDetail

錯誤詳細數據。

ErrorResponse

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

JsonFormat

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

Pollutant

在查詢位置測量的單一污染物,則以一個項目返回。AirQuality.pollutants 每個條目都會以代碼和英文名稱標示污染物,報告其在空氣中測量 concentration 結果,並列出污染物在當地AQI(index)和國際標準化指數(globalIndex)中的個別貢獻——這兩個量表與整體讀數 AirQuality相同的,但僅限於該污染物。 一般的空氣品質讀數會針對每種污染物——氮氧化物、臭氧、顆粒物10、顆粒物2.5、一氧化碳和二氧化硫——各有一個條目,讓來電者能看到存在哪些物質以及各自貢獻多少。

PollutantType

Azure 地圖服務 氣象服務追蹤的六種污染物類型說明。

UnitType

與顯示單位類型相關的整數值。 例如,17 表示攝氏度,18 表示華氏度。 可用於單位轉換。 欲了解更多資訊,請參閱氣象服務Azure 地圖服務。

WeatherValue

天氣相關指標的數值,如溫度、露點及風速,以公制或英制單位表示,並依單位 URI 參數指定。 欲了解更多資訊,請參閱《Azure 地圖服務 中的天氣服務》一文中的單元類型。

AirQuality

某一地點的當前空氣品質讀數,則以 的 AirQualityResult.results條目返回。 結合當地監管機構報告的空氣品質指數(index)與國際標準化指數(globalIndex),識別 dominantPollutant 結果驅動因素,並與適合色彩編碼介面的本地定性 category 及匹配 categoryColor 配對。 短片 description 說明該讀數對日常活動及健康注意事項的意義,當請求要求污染物細節時, pollutants 陣列會呈現每項污染物的分解。

名稱 類型 Description
category

string

一份簡短的質性空氣品質摘要,依申請中指定語言回傳。 典型的數值包括 良好、 一般、 中等、 差和 危險;具體的數值依據所查詢地點的監管機構而定。

categoryColor

string

一個十六進位顏色代碼匹配 category,適用於用顏色編碼使用者介面中的空氣品質讀數——例如, #FFC300 代表 「公平」。 每個 category 數值都有獨特的顏色,讓讀數一眼就能辨識。

dateTime

string (date-time)

空氣品質讀數適用的日期與時間,ISO 8601 格式(yyyy-mm-ddThh:mm:ss+hh:mm)。 例如, 2021-07-19T02:00:00+00:00。

description

string

請以請求中指定的語言,自由表達一兩句說明當前空氣品質及敏感群體應考慮的預防措施。 例如,空氣 品質對大多數人來說通常是可接受的。然而,敏感族群可能因長期暴露而出現輕微到中度的症狀。

dominantPollutant

DominantPollutant

驅動電流 index 和 globalIndex 的 DominantPollutant 污染物,例如 臭氧 或 NO2。 有助於辨識哪種物質對當前空氣品質最為重要。

globalIndex

number (float)

一種標準化空氣品質指數,設計用來跨地點可比較,獨立於任何當地的AQI指數。 該值為六種被測污染物(PM2.5、 PM10、 NO2、 SO2、 CO、 O3)中最高的個別子指數;產生該最大值的污染物會在 中回傳 dominantPollutant。

範圍與類別:

價值 Category
0-20 非常好
21-50 尚可
51-100 差
101-150 狀況不良
151-250 非常不健康
251+ 危險

例如,給定子指數CO 0.6、SO2 1.1、PM2.5 6.5、NO2 6.7、PM10 12.2、O3 22.1, globalIndex 為 22.1 且 dominantPollutant 為 臭氧。

index

number (float)

當地監管機構為查詢地點設定的空氣品質指數(AQI)。 AQI 量表在不同國家和地區間差異很大,因此同一數值在不同地點可能有不同的意義—— category 用於標籤在不同地點間保持一致。 例如,根據查詢地點的量表,是 21.6 。 背景請參見維基百科上的 空氣品質指數 。

pollutants

Pollutant[]

整體讀數背後有各污染物細節,每個被測物種(通常為氮氧化物、臭氧、顆粒物10、顆粒物2.5、一氧化碳及二氧化硫)各有一條Pollutant條目。 每條目報告污染物的濃度及其個別 index 與 globalIndex 貢獻。 只有當請求要求污染物細節時才會回傳。

AirQualityResult

回應由「取得當前空氣品質」操作回傳,提供指定地點的當前空氣品質狀況。 陣 results 列包含一個 AirQuality 條目,總結本地及全球標準化的空氣品質指數、主要污染物、質性分類及匹配顏色、健康影響的簡短描述,以及(如有需求)各污染物細節。

名稱 類型 Description
nextLink

string

當回應分頁時,用來檢索下一頁結果的 URL,適合瀏覽過於龐大無法一次呼叫回傳的結果集。 當沒有其他頁面時,空白。

results

AirQuality[]

該地點目前的空氣品質讀數以單元件陣列形式回傳。 條目報告當地空氣品質指數(index)、國際標準化指數(globalIndexdominantPollutant)、(例如臭氧層)、具匹配categoryColor度的質category性指數(如一般指數,例如 #FFC300)、健康影響簡短description說明,以及當請求要求污染物細節時,則有一個pollutants陣列,每個被測量污染物都設一個條目。

DominantPollutant

識別濃度最高的污染物。

值 Description
Carbon Monoxide

一氧化碳(CO)是一種無色、無味、無味但高度有毒的氣體,由含碳燃料不完全燃燒所產生。 常見來源包括汽車尾氣、燃氣灶、熔爐和柴火。

Nitrogen Dioxide

二氧化氮(NO2)是大氣中的重要污染物。 它受到世界衛生組織 (WHO) 制定的建議限值指南的監管和約束。

Ozone

臭氧(O3)是光化學煙霧的關鍵成分,這種棕色有害的霧氣籠罩許多大城市,源自陽光與特定污染物之間的光化學反應。

Particulate Matter 2.5

顆粒物2.5(PM2.5)指的是直徑通常為2.5微米及以下的細顆粒。 這些顆粒比人類頭髮細超過100倍,且能長時間懸浮在空氣中。

Particulate Matter 10

顆粒物10(PM10)指的顆粒直徑通常為10微米或更小。 這些顆粒可能包括灰塵、花粉、煙灰、煙霧和液滴。

Sulfur Dioxide

二氧化硫(SO2)是一種重、無色的無機氣體,具有刺鼻且令人不悅的氣味。 它主要通過在發電廠和工業設施中燃燒化石燃料產生,但也可以從火山等自然來源排放。

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 物件。

JsonFormat

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

值 Description
json

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

Pollutant

在查詢位置測量的單一污染物,則以一個項目返回。AirQuality.pollutants 每個條目都會以代碼和英文名稱標示污染物,報告其在空氣中測量 concentration 結果,並列出污染物在當地AQI(index)和國際標準化指數(globalIndex)中的個別貢獻——這兩個量表與整體讀數 AirQuality相同的,但僅限於該污染物。 一般的空氣品質讀數會針對每種污染物——氮氧化物、臭氧、顆粒物10、顆粒物2.5、一氧化碳和二氧化硫——各有一個條目,讓來電者能看到存在哪些物質以及各自貢獻多少。

名稱 類型 Description
concentration

WeatherValue

污染物在空氣中測得的濃度,以微克每立方米(μg/m³)計,針對NO2、O3、PM10、PM2.5、CO和SO2,例如臭氧為53.5 μg/m³,氮氧化物為13.4 μg/m³,或以百萬分之一(ppm)為單位。 濃度是將 indexglobalIndex和 輸入的原始測量值。

globalIndex

number (float)

這種污染物對國際標準化空氣品質指數的貢獻,與 0 到 300+ 的比例 AirQuality.globalIndex 相同,以便跨地點比較各污染物數值。 數值越高,代表對空氣品質不良的貢獻越大。 例如,臭氧為22.1,二氧化氮為6.7。

index

number (float)

此污染物對當地監管機構所設定的整體空氣品質指數(AQI)的貢獻。 使用與 相同的局部尺度AirQuality.index,因此原始數字可與同一地點的整體讀數比較,但無法直接跨地點比較——例如,臭氧在總讀數為 index21.6(臭氧為主要污染物)時,臭氧為 21.6。 背景請參見維基百科上的 空氣品質指數 。

name

string

該污染物的英文名稱與type以下對應詞,例如:二氧化氮(NO2)、臭氧(O3)、PM10(PM10)、PM2.5(PM2.5)為懸浮粒子2.5、一氧化碳(CO)或二氧化硫(SO2)。 無論請求語言為何,都會以英文回傳,因此在不需要本地化文字時,適合作為穩定的顯示標籤。

type

PollutantType

污染物代碼作為穩定且語言無關的識別碼—— PollutantType 是以下數值之一(PM2.5、 PM10、 O3、 NO2、 SO2或 CO)。 未來可能會加入更多污染物類型。

PollutantType

Azure 地圖服務 氣象服務追蹤的六種污染物類型說明。

值 Description
CO

過去一小時內一氧化碳(CO)的平均濃度(微克每立方米,μg/m³)。

一氧化碳是一種無色、無味、無味但高度有毒的氣體,由含碳燃料不完全燃燒所產生。 常見來源包括汽車尾氣、燃氣灶、熔爐和柴火。

NO2

過去一小時內二氧化氮(NO2)的平均濃度(微克每立方米,μg/m³)。

NO2 是大氣中重要的污染物。 它受到世界衛生組織 (WHO) 制定的建議限值指南的監管和約束。

O3

過去一小時內臭氧(O3)的平均濃度(微克每立方米,μg/m³)。

O3是光化學煙霧的關鍵成分,這種棕色有害的霧氣籠罩許多大城市,是由陽光與特定污染物之間的光化學反應所產生。

PM2.5

過去一小時內,直徑小於2.5微米的顆粒平均濃度,以微克每立方米(μg/m³)計算。

PM2.5,也稱為氣溶膠,由懸浮在空氣中的細微塵埃和微小液滴組成。

PM10

過去一小時內,直徑介於2.5至10微米之間的顆粒平均濃度,以微克每立方米(μg/m³)為單位。

懸浮於空氣中的微粒10(PM10),也稱為氣溶膠,由懸浮在空氣中的細微塵埃和微小液滴組成。

SO2

過去一小時內二氧化硫(SO2)的平均濃度(微克每立方米,μg/m³)。

SO2是一種致密、無色的無機氣體,帶有刺鼻且令人不適的氣味。 它主要由發電廠和工業設施燃燒化石燃料產生,但也可能從火山等自然來源排放。

UnitType

與顯示單位類型相關的整數值。 例如,17 表示攝氏度,18 表示華氏度。 可用於單位轉換。 欲了解更多資訊,請參閱氣象服務Azure 地圖服務。

值 Description
0

feet

1

inches

2

miles

3

millimeter

4

centimeter

5

計量

6

kilometer

7

kilometersPerHour

8

knots

9

milesPerHour

10

metersPerSecond

11

hectoPascals

12

inchesOfMercury

13

kiloPascals

14

millibars

15

millimetersOfMercury

16

poundsPerSquareInch

17

Celsius

18

Fahrenheit

19

kelvin

20

percent

21

float

22

整數

31

MicrogramsPerCubicMeterOfAir

WeatherValue

天氣相關指標的數值,如溫度、露點及風速,以公制或英制單位表示,並依單位 URI 參數指定。 欲了解更多資訊,請參閱《Azure 地圖服務 中的天氣服務》一文中的單元類型。

名稱 類型 Description
unit

string

回傳值中使用的計量單位,例如「C」代表攝氏,「F」代表華氏。

unitType

UnitType

一個整數代表單位的類型。 例如,0代表英尺,1代表英吋,2代表英里。 完整列表請參閱《Azure 地圖服務 中的氣象服務》一文中的單元類型。

value

number (float)

以指定單位表示的測量值。