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公有雲用 |
|
format
|
path | True |
回應所需的格式。 僅支援 |
|
|
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 |
要求已成功。 |
|
| Other Status Codes |
未預期的錯誤回應。 |
安全性
AadToken
這些是Microsoft Entra OAuth 2.0流。 當與 Azure 基於角色的存取 控制結合時,可以用來控制對 Azure 地圖服務 REST API 的存取。 Azure 角色基礎存取控制用於指定對一個或多個 Azure 地圖服務 資源帳號或子資源的存取權限。 任何使用者、群組或服務主體都可以透過內建角色或由一或多個 Azure 地圖服務 REST 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 地圖服務資源
使用此令牌時,任何應用程式都有權使用 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 |
|---|---|
|
Air |
某一地點的當前空氣品質讀數,則以 的 |
|
Air |
回應由「取得當前空氣品質」操作回傳,提供指定地點的當前空氣品質狀況。 陣 |
|
Dominant |
識別濃度最高的污染物。 |
|
Error |
資源管理錯誤其他資訊。 |
|
Error |
錯誤詳細數據。 |
|
Error |
所有 Azure Resource Manager API 的常見錯誤回應,用於回傳失敗操作的錯誤細節。 (這也遵循 OData 錯誤回應格式。)。 |
|
Json |
回應所需的格式。 僅支援 |
| Pollutant |
在查詢位置測量的單一污染物,則以一個項目返回。 |
|
Pollutant |
Azure 地圖服務 氣象服務追蹤的六種污染物類型說明。 |
|
Unit |
與顯示單位類型相關的整數值。 例如,17 表示攝氏度,18 表示華氏度。 可用於單位轉換。 欲了解更多資訊,請參閱氣象服務Azure 地圖服務。 |
|
Weather |
天氣相關指標的數值,如溫度、露點及風速,以公制或英制單位表示,並依單位 URI 參數指定。 欲了解更多資訊,請參閱《Azure 地圖服務 中的天氣服務》一文中的單元類型。 |
AirQuality
某一地點的當前空氣品質讀數,則以 的 AirQualityResult.results條目返回。 結合當地監管機構報告的空氣品質指數(index)與國際標準化指數(globalIndex),識別 dominantPollutant 結果驅動因素,並與適合色彩編碼介面的本地定性 category 及匹配 categoryColor 配對。 短片 description 說明該讀數對日常活動及健康注意事項的意義,當請求要求污染物細節時, pollutants 陣列會呈現每項污染物的分解。
| 名稱 | 類型 | Description | ||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| category |
string |
一份簡短的質性空氣品質摘要,依申請中指定語言回傳。 典型的數值包括 良好、 一般、 中等、 差和 危險;具體的數值依據所查詢地點的監管機構而定。 |
||||||||||||||
| categoryColor |
string |
一個十六進位顏色代碼匹配 |
||||||||||||||
| dateTime |
string (date-time) |
空氣品質讀數適用的日期與時間,ISO 8601 格式(yyyy-mm-ddThh:mm:ss+hh:mm)。 例如, 2021-07-19T02:00:00+00:00。 |
||||||||||||||
| description |
string |
請以請求中指定的語言,自由表達一兩句說明當前空氣品質及敏感群體應考慮的預防措施。 例如,空氣 品質對大多數人來說通常是可接受的。然而,敏感族群可能因長期暴露而出現輕微到中度的症狀。 |
||||||||||||||
| dominantPollutant |
驅動電流 |
|||||||||||||||
| globalIndex |
number (float) |
一種標準化空氣品質指數,設計用來跨地點可比較,獨立於任何當地的AQI指數。 該值為六種被測污染物(PM2.5、 PM10、 NO2、 SO2、 CO、 O3)中最高的個別子指數;產生該最大值的污染物會在 中回傳 範圍與類別:
例如,給定子指數CO 0.6、SO2 1.1、PM2.5 6.5、NO2 6.7、PM10 12.2、O3 22.1, |
||||||||||||||
| index |
number (float) |
當地監管機構為查詢地點設定的空氣品質指數(AQI)。 AQI 量表在不同國家和地區間差異很大,因此同一數值在不同地點可能有不同的意義—— |
||||||||||||||
| pollutants |
整體讀數背後有各污染物細節,每個被測物種(通常為氮氧化物、臭氧、顆粒物10、顆粒物2.5、一氧化碳及二氧化硫)各有一條 |
AirQualityResult
回應由「取得當前空氣品質」操作回傳,提供指定地點的當前空氣品質狀況。 陣 results 列包含一個 AirQuality 條目,總結本地及全球標準化的空氣品質指數、主要污染物、質性分類及匹配顏色、健康影響的簡短描述,以及(如有需求)各污染物細節。
| 名稱 | 類型 | Description |
|---|---|---|
| nextLink |
string |
當回應分頁時,用來檢索下一頁結果的 URL,適合瀏覽過於龐大無法一次呼叫回傳的結果集。 當沒有其他頁面時,空白。 |
| results |
該地點目前的空氣品質讀數以單元件陣列形式回傳。 條目報告當地空氣品質指數( |
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 |
錯誤其他資訊。 |
|
| code |
string |
錯誤碼。 |
| details |
錯誤詳情 |
|
| message |
string |
錯誤訊息。 |
| target |
string |
錯誤目標。 |
ErrorResponse
所有 Azure Resource Manager API 的常見錯誤回應,用於回傳失敗操作的錯誤細節。 (這也遵循 OData 錯誤回應格式。)。
| 名稱 | 類型 | Description |
|---|---|---|
| error |
error 物件。 |
JsonFormat
回應所需的格式。 僅支援 json 格式。
| 值 | Description |
|---|---|
| json |
Pollutant
在查詢位置測量的單一污染物,則以一個項目返回。AirQuality.pollutants 每個條目都會以代碼和英文名稱標示污染物,報告其在空氣中測量 concentration 結果,並列出污染物在當地AQI(index)和國際標準化指數(globalIndex)中的個別貢獻——這兩個量表與整體讀數 AirQuality相同的,但僅限於該污染物。 一般的空氣品質讀數會針對每種污染物——氮氧化物、臭氧、顆粒物10、顆粒物2.5、一氧化碳和二氧化硫——各有一個條目,讓來電者能看到存在哪些物質以及各自貢獻多少。
| 名稱 | 類型 | Description |
|---|---|---|
| concentration |
污染物在空氣中測得的濃度,以微克每立方米(μg/m³)計,針對NO2、O3、PM10、PM2.5、CO和SO2,例如臭氧為53.5 μg/m³,氮氧化物為13.4 μg/m³,或以百萬分之一(ppm)為單位。 濃度是將 |
|
| globalIndex |
number (float) |
這種污染物對國際標準化空氣品質指數的貢獻,與 0 到 300+ 的比例 |
| index |
number (float) |
此污染物對當地監管機構所設定的整體空氣品質指數(AQI)的貢獻。 使用與 相同的局部尺度 |
| name |
string |
該污染物的英文名稱與 |
| type |
污染物代碼作為穩定且語言無關的識別碼—— |
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 |
一個整數代表單位的類型。 例如,0代表英尺,1代表英吋,2代表英里。 完整列表請參閱《Azure 地圖服務 中的氣象服務》一文中的單元類型。 |
|
| value |
number (float) |
以指定單位表示的測量值。 |