Package google.maps.airquality.v1

索引

AirQuality

空氣品質服務。

LookupCurrentConditions

rpc LookupCurrentConditions(LookupCurrentConditionsRequest) returns (LookupCurrentConditionsResponse)

Current Conditions 端點提供超過 100 個國家/地區的空氣品質資訊，解析度最高可達 500 x 500 公尺。包括超過 70 個當地指數、全球空氣品質指數和類別。

授權範圍

需要下列 OAuth 範圍：

  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱 OAuth 2.0 總覽。
LookupForecast

rpc LookupForecast(LookupForecastRequest) returns (LookupForecastResponse)

傳回特定時間範圍內特定地區的空氣品質預測資料。

授權範圍

需要下列 OAuth 範圍：

  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱 OAuth 2.0 總覽。
LookupHeatmapTile

rpc LookupHeatmapTile(LookupHeatmapTileRequest) returns (HttpBody)

傳回包含圖塊 PNG 圖片資料的位元組陣列。

授權範圍

需要下列 OAuth 範圍：

  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱 OAuth 2.0 總覽。
LookupHistory

rpc LookupHistory(LookupHistoryRequest) returns (LookupHistoryResponse)

傳回特定時間範圍內特定地區的空氣品質記錄。

授權範圍

需要下列 OAuth 範圍：

  • https://www.googleapis.com/auth/cloud-platform

詳情請參閱 OAuth 2.0 總覽。

AirQualityIndex

代表不同空氣品質指標的基本物件。這些指標整合後，會提供目前空氣品質狀況的數據匯報。世上有多個指數，除了用途不同，也有團體需要評估不同部分的空氣品質。

欄位
code

string

索引的程式碼。這個欄位代表程式設計目的的索引，使用 Snake 大小寫 (而非空格)。例如：「uaqi」、「fra_atmo」。
display_name

string

人類可讀的索引名稱表示法。例如：「AQI (美國)」
aqi_display

string

索引數值分數的文字表示法，可能包含前置或後置符號，通常代表最差的索引分數。範例：>100 或 10+。

注意：如要顯示索引分數，請使用這個欄位。若索引非數字，這個欄位會空白。
color

Color

用來代表 AQI 數字分數的顏色。
category

string

索引數值分數解讀的文字分類。例如：「空氣品質極佳」。
dominant_pollutant

string

主汙染物的化學符號。例如「CO」。
aqi

int32

索引的數值分數。範例：10、100。

這個值並未正規化，因此只應在相關的空氣品質指數時解釋。如為非數字的索引，系統不會傳回這個欄位。

注意：這個欄位應該用於計算、圖表顯示等。如要顯示索引分數，請使用 AQI 顯示欄位。

ColorPalette

決定「通用空氣品質指數」(UAQI) 提供的資料所使用的調色盤。這個調色盤僅適用於 UAQI，其他 AQI 則是具有無法控制的預定調色盤。

列舉
COLOR_PALETTE_UNSPECIFIED 預設值。如果以參數的形式傳遞，則系統會忽略這項設定。
RED_GREEN 判斷是否使用紅色/綠色調色盤。
INDIGO_PERSIAN_DARK 判斷是否要使用靛藍色/波斯調色盤 (深色主題)。
INDIGO_PERSIAN_LIGHT 判斷是否要使用靛藍色/波斯調色盤 (淺色主題)。

CustomLocalAqi

表示「國家/地區與 AQI」的關係。將國家/地區與所需的 AQI 配對，即可根據所選 AQI 顯示該國家/地區所需的空氣品質資料。

欄位
region_code

string

需要自訂 AQI 的國家/地區。請使用 ISO 3166-1 alpha-2 代碼提供值。
aqi

string

要與國家/地區建立關聯的 AQI。值必須是有效的索引代碼。

ExtraComputation

其他可視需要啟用的功能。指定額外的運算將在回應中傳回相關的元素和欄位。

列舉
EXTRA_COMPUTATION_UNSPECIFIED 預設值。如果以參數的形式傳遞，伺服器會予以忽略。
LOCAL_AQI

決定回應中是否要包含要求位置 (國家/地區) 的當地 (國家/地區) 空氣品質指數。

如有指定，回應就會包含「air_quality_index」資料結構，內含地點本機 AQI 的所有相關資料。
HEALTH_RECOMMENDATIONS

依據目前 AQI 狀況，決定回應內容是否包含健康建議和建議行動。

這些建議是為一般大眾和六個含有風險族群 (比一般大眾更敏感) 而量身打造的。

如果有指定，系統會在有相關資料時，在回應中填入 health_recommendations 欄位。
POLLUTANT_ADDITIONAL_INFO

決定是否要在回應中加入每個汙染物的其他資訊。

如果有指定，「索引」欄位回應中包含的每個空氣品質索引物件都會在資料可用時納入 additional_info 欄位。
DOMINANT_POLLUTANT_CONCENTRATION

決定回應是否包括根據全域和/或本機指數測量的主要汙染物濃度。

如果要求同時指定全域 AQI 和本地 AQI，最多可能會傳回兩組汙染物代碼。

如果有指定，系統在資料可用時，就會納入「汙染物」清單中的主要汙染物物件。concentration
POLLUTANT_CONCENTRATION

依據全域和/或本機指數，決定回應是否納入所有具有可用測量方式的汙染物濃度。

如果有指定，回應中「汙染物」欄位中包含的每個汙染物件，在資料可用時都會包含 concentration 欄位。

HealthRecommendations

針對不同族群 (以任意文字格式) 提供的健康建議。這些建議是根據其相關聯的空氣品質條件計算得出。

欄位
general_population

string

無特別機密。
elderly

string

退休人士和年齡比一般人口還要高的族群。
lung_disease_population

string

呼吸相關問題和氣喘患者。
heart_disease_population

string

心臟和循環系統疾病。
athletes

string

運動和其他激烈的戶外活動。
pregnant_women

string

孕育各階段的女性。
children

string

兒童、幼兒和嬰兒等年幼人口。

LookupCurrentConditionsRequest

要求的空氣品質目前狀況。

欄位
location

LatLng

必要欄位。API 用來尋找空氣品質目前狀況資料的經緯度。
extra_computations[]

ExtraComputation

選用設定。其他可視需要啟用的功能。指定額外的運算將在回應中傳回相關的元素和欄位。
uaqi_color_palette

ColorPalette

選用設定。決定「環球空氣品質指數」(UAQI) 提供的資料所使用的調色盤。這個調色盤僅適用於 UAQI，其他 AQI 則是具有無法控制的預定調色盤。
custom_local_aqis[]

CustomLocalAqi

選用設定。表示「國家/地區與 AQI」的關係。將國家/地區與所需的 AQI 配對，即可根據所選 AQI 顯示該國家/地區所需的空氣品質資料。這個參數可用來指定特定國家/地區的非預設的 AQI。舉例來說，如要取得加拿大的美國 EPA 索引，而不是加拿大的預設索引值。
universal_aqi

bool

選用設定。如果設為 True，系統會將通用 AQI 納入回應的「索引」欄位。預設值為 true。
language_code

string

選用設定。允許用戶端選擇回應的語言。如果無法提供該語言的資料，API 會使用最接近的項目。允許的值採用 IETF 標準。預設值為 en (英文)。

LookupCurrentConditionsResponse

欄位
date_time

Timestamp

採用 RFC3339 世界標準時間「Zulu」格式的四捨五入時間戳記，採用奈秒解析度和最多九個小數位數。例如：「2014-10-02T15:00:00Z」。
region_code

string

與要求中所列位置相對應的國家/地區的 ISO_3166-1 alpha-2 代碼。如果要求中提供的地點位於有爭議的地域，回應可能會省略這個欄位。
indexes[]

AirQualityIndex

根據要求參數，這份清單會包含 (最多) 個空氣品質索引：

  • 通用空氣品質指數。如果通用 Aqi 布林值設為 True，就會傳回 。
  • 本地空氣品質指數。如果指定 LOCAL_AQI 額外計算，將傳回。
pollutants[]

Pollutant

影響要求中指定位置的汙染物清單。注意： 只有在要求指定下列一或多項額外運算時，才會傳回此欄位：POLLUTANT_ADDITIONAL_INFO、DOINANT_POLLUTANT_CONCENTRATION、POLLUTANT_CONCENTRATION。
health_recommendations

HealthRecommendations

與已回報空氣品質狀況相關的健康建議和應變措施。系統會針對有風險的族群、汙染物敏感度較高的族群及一般大眾，量身打造不同的推薦內容。

LookupForecastRequest

空氣品質預測 API 的要求物件。

欄位
location

LatLng

必要欄位。API 尋找空氣品質資料的經緯度。
extra_computations[]

ExtraComputation

選用設定。其他可視需要啟用的功能。指定額外的運算將在回應中傳回相關的元素和欄位。
uaqi_color_palette

ColorPalette

選用設定。決定「環球空氣品質指數」(UAQI) 提供的資料所使用的調色盤。這個調色盤僅適用於 UAQI，其他 AQI 則是具有無法控制的預定調色盤。
custom_local_aqis[]

CustomLocalAqi

選用設定。表示「國家/地區與 AQI」的關係。將國家/地區與所需的 AQI 配對，即可根據所選 AQI 顯示該國家/地區所需的空氣品質資料。這個參數可用來指定特定國家/地區的非預設的 AQI。舉例來說，如要取得加拿大的美國 EPA 索引，而不是加拿大的預設索引值。
page_size

int32

選用設定。每頁傳回的每小時資訊記錄數量上限 (預設為 24)。
page_token

string

選用設定。接收自先前的預測呼叫傳送的網頁權杖。可用來擷取後續網頁。
聯集欄位 time_range。必要空氣品質預測資料的時間範圍。範圍至少須有一個經過四捨五入的小時。如未指定這個欄位，將導致 INVALID_GIVEN 錯誤。time_range 只能是下列其中一項：
date_time

Timestamp

傳回特定時間點的資料時間戳記。系統會將時間戳記四捨五入至前一個小時。

注意：這會僅傳回要求的時間戳記 (例如一個每小時資訊元素) 的每小時資料。舉例來說，如果要求在 date_time 參數設為 2023-01-03T11:05:49Z 的情況下傳送，要求會無條件捨去為 2023-01-03T11:00:00Z。
period

Interval

指出取得預測資料的開始和結束時間。系統會將時間戳記四捨五入至前一個小時。
universal_aqi

bool

選用設定。如果設為 True，系統會將通用 AQI 納入回應的「indexes」欄位 (預設值 = true)。
language_code

string

選用設定。允許用戶端選擇回應的語言。如果無法提供該語言的資料，API 會使用最接近的項目。允許的值須採用 IETF 標準 (預設值為「en」)。

LookupForecastResponse

空氣品質預測 API 的回應物件。

欄位
hourly_forecasts[]

HourlyForecast

選用設定。包含要求範圍內每小時的空氣品質資訊。舉例來說，如果請求的是 48 小時的預測資料，每小時天氣預報就會有 48 個元素。
region_code

string

選用設定。與要求中所列位置相對應的國家/地區的 ISO_3166-1 alpha-2 代碼。如果要求中提供的地點位於有爭議的地域，回應可能會省略這個欄位。
next_page_token

string

選用設定。用於擷取下一頁的符記。

HourlyForecast

包含要求範圍內每小時的空氣品質資訊。舉例來說，如果請求的是 48 小時的預測資料，每小時天氣預報就會有 48 個元素。

欄位
date_time

Timestamp

經過四捨五入的時間戳記，代表資料參照的時間 (小時)，採用 RFC3339 UTC Zulu 格式。例如：「2014-10-02T15:00:00Z」。
indexes[]

AirQualityIndex

根據要求參數，這份清單會包含 (最多) 個空氣品質索引：

  • 通用空氣品質指數。如果 universal_aqi 布林值設為 true，系統會傳回此值。
  • 本地空氣品質指數。如果指定 LOCAL_AQI 額外計算，將傳回。
pollutants[]

Pollutant

影響要求中指定位置的汙染物清單。

注意： 只有在要求指定下列一或多項額外運算時，才會傳回此欄位：POLLUTANT_ADDITIONAL_INFO、DOINANT_POLLUTANT_CONCENTRATION、POLLUTANT_CONCENTRATION。
health_recommendations

HealthRecommendations

與已回報空氣品質狀況相關的健康建議和應變措施。系統會針對有風險的族群、汙染物敏感度較高的族群及一般大眾，量身打造不同的推薦內容。

LookupHeatmapTileRequest

熱視圖圖塊要求。

該結構遵循標準圖塊伺服器 GET 呼叫，即 https://airquality.googleapis.com/v1/mapTypes/{map_type}/heatmapTiles/{zoom}/{x}/{y}

範例：https://airquality.googleapis.com/v1/mapTypes/BAQI_INDIGO_PERSIAN/heatmapTiles/1/1/1

欄位
map_type

MapType

必要欄位。空氣品質熱視圖的類型。定義地圖要以圖形呈現的汙染物。

Allowed values:
- UAQI_RED_GREEN (UAQI, red-green palette)
- UAQI_INDIGO_PERSIAN (UAQI, indigo-persian palette)
- PM25_INDIGO_PERSIAN
- GBR_DEFRA
- DEU_UBA
- CAN_EC
- FRA_ATMO
- US_AQI
zoom

int32

必要欄位。地圖的縮放等級。定義地圖內容在地圖檢視中的顯示方式。

縮放等級 0 是單一圖塊中的全世界。縮放等級 1 代表整個世界，共有 4 個圖塊。縮放等級 2 是 16 個圖塊中的整個世界。縮放等級 16 代表全世界 65,536 個圖塊。

允許的值：0 至 16
x

int32

必要欄位。定義要求方塊中的東西點。
y

int32

必要欄位。定義要求圖塊中的南北點。

LookupHistoryRequest

空氣品質記錄 API 的要求物件。

欄位
page_size

int32

選用設定。每頁傳回的每小時資訊記錄數量上限。預設值為 72，最大值為 168 (資料 7 天)。
page_token

string

選用設定。接收自先前記錄呼叫的網頁權杖。可用來擷取後續網頁。

請注意，為這個參數提供值時，您提供的所有其他參數都必須與提供網頁符記的呼叫 (先前的呼叫) 相符。
location

LatLng

必要欄位。API 尋找空氣品質記錄資料的經緯度。
extra_computations[]

ExtraComputation

選用設定。其他可視需要啟用的功能。指定額外的運算將在回應中傳回相關的元素和欄位。
uaqi_color_palette

ColorPalette

選用設定。決定「環球空氣品質指數」(UAQI) 提供的資料所使用的調色盤。這個調色盤僅適用於 UAQI，其他 AQI 則是具有無法控制的預定調色盤。
custom_local_aqis[]

CustomLocalAqi

選用設定。表示「國家/地區與 AQI」的關係。將國家/地區與所需的 AQI 配對，即可根據所選 AQI 顯示該國家/地區所需的空氣品質資料。這個參數可用來指定特定國家/地區的非預設的 AQI。舉例來說，如要取得加拿大的美國 EPA 索引，而不是加拿大的預設索引值。
聯集欄位 time_range。所需空氣品質資料的時間範圍。如果未指定任何時間範圍相關欄位，就會產生 INVALID_Gradle 錯誤。time_range 只能是下列其中一個項目：time_range 只能是下列其中一個值：
date_time

Timestamp

要傳回歷來資料的時間戳記。系統會將時間戳記四捨五入至前一個小時。

注意：這會僅傳回要求的時間戳記 (例如一個每小時資訊元素) 的每小時資料。舉例來說，如果要求在 dateTime 參數設為 2023-01-03T11:05:49Z 的情況下傳送，要求會無條件捨去為 2023-01-03T11:00:00Z。

採用 RFC3339 世界標準時間「Zulu」格式的時間戳記，採用奈秒解析度和最多九個小數位數。例如：「2014-10-02T15:01:23Z」和「2014-10-02T15:01:23.045123456Z」。
hours

int32

介於 1 到 720 的數字，表示要求的小時範圍。舉例來說，如果值為 48，系統會傳回過去 48 小時的資料。
period

Interval

表示要取得歷史資料的開始和結束日期。系統會將時間戳記四捨五入至前一個小時。
universal_aqi

bool

選用設定。如果設為 True，系統會將通用 AQI 納入回應的「索引」欄位。預設值為 true。
language_code

string

選用設定。允許用戶端選擇回應的語言。如果無法提供該語言的資料，API 會使用最接近的項目。允許的值採用 IETF 標準。預設值為 en (英文)。

LookupHistoryResponse

欄位
hours_info[]

HourInfo

選用設定。包含要求範圍內每小時的空氣品質資訊。舉例來說，如果要求的時間是 48 小時，報表就會顯示 48 個每小時資訊元素。
region_code

string

選用設定。與要求中所列位置相對應的國家/地區的 ISO_3166-1 alpha-2 代碼。如果要求中提供的地點位於有爭議的地域，回應可能會省略這個欄位。
next_page_token

string

選用設定。用於擷取下一頁的符記。

HourInfo

包含要求範圍內每小時的空氣品質資訊。舉例來說，如果要求的時間是 48 小時，報表就會顯示 48 個每小時資訊元素。

欄位
date_time

Timestamp

經過四捨五入的時間戳記，表示資料採用 RFC3339 世界標準時間「Zulu」格式的時間，採用奈秒解析度和最多九個小數位數。例如：「2014-10-02T15:00:00Z」。
indexes[]

AirQualityIndex

根據要求參數，這份清單會包含 (最多) 個空氣品質索引：

  • 通用空氣品質指數。如果通用 Aqi 布林值設為 True，就會傳回 。
  • 本地空氣品質指數。如果指定 LOCAL_AQI 額外計算，將傳回。
pollutants[]

Pollutant

影響要求中指定位置的汙染物清單。注意： 只有在要求指定下列一或多項額外運算時，才會傳回此欄位：POLLUTANT_ADDITIONAL_INFO、DOINANT_POLLUTANT_CONCENTRATION、POLLUTANT_CONCENTRATION。
health_recommendations

HealthRecommendations

與已回報空氣品質狀況相關的健康建議和應變措施。系統會針對有風險的族群、汙染物敏感度較高的族群及一般大眾，量身打造不同的推薦內容。

MapType

空氣品質熱視圖的類型。定義地圖要以圖形呈現的汙染物。

列舉
MAP_TYPE_UNSPECIFIED 預設值。如果以參數的形式傳遞，伺服器會予以忽略。
UAQI_RED_GREEN 通用空氣品質指數紅/綠調色盤。
UAQI_INDIGO_PERSIAN 世界空氣品質指數 (靛藍色調色盤)。
PM25_INDIGO_PERSIAN PM2.5 索引調色盤。
GBR_DEFRA 每日空氣品質指數 (英國) 調色盤。
DEU_UBA 德國當地空氣品質指數調色盤。
CAN_EC 加拿大空氣品質健康指數調色盤。
FRA_ATMO 法國空氣品質指數調色盤。
US_AQI 美國空氣品質指數調色盤。

汙染物

空氣品質汙染物相關資料。

欄位
code

string

污染物的代號名稱。例如「so2」。如需所有可用代碼的清單，請按這裡。
display_name

string

汙染物的顯示名稱。例如「NOx」。
full_name

string

汙染物的全名。如為化學化合物，這會是 IUPAC 的名稱。例如：「二氧化硫」。

如要進一步瞭解 IUPAC 名稱表格，請參閱 https://iupac.org/what-we-do/periodic-table-of-elements/
concentration

Concentration

汙染物濃度是由其中一個標準空氣汙染測量單位測得的濃度。
additional_info

AdditionalInfo

污染物的其他相關資訊。

AdditionalInfo

特定汙染物的排放來源和健康影響。

欄位
sources

string

表示污染物主要排放來源的文字。
effects

string

表示污染物主要健康影響的文字。

濃度

空氣中特定汙染物的濃度。

欄位
units

Unit

測量此汙染物濃度的單位。
value

float

汙染濃度值。

Unit

定義用來測量汙染物濃度的單位。

列舉
UNIT_UNSPECIFIED 未指定的濃度單位。
PARTS_PER_BILLION ppb (每十億個) 濃度單位。
MICROGRAMS_PER_CUBIC_METER 「μg/m^3」(每立方公尺的微克) 濃度單位。