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

索引的代码。此字段使用蛇形命名法（而非空格）表示编程用途的索引。示例：“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

确定是否在响应中包含所请求地点（国家/地区）的本地（国家/地区）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，则 Universal AQI 将包含在响应的“indexes”字段中。默认值为 true。
language_code

string

可选。允许客户端选择响应的语言。如果无法为该语言提供数据，API 会使用最接近的匹配项。允许的值取决于 IETF 标准。默认值为 en。

LookupCurrentConditionsResponse

字段
date_time

Timestamp

采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式向下舍入的时间戳，精确到纳秒，最多九位小数。例如：“2014-10-02T15:00:00Z”。
region_code

string

与请求中提供的位置对应的国家/地区的 ISO_3166-1 alpha-2 代码。如果要求中提供的地点位于有争议的地区，响应中可能会省略此字段。
indexes[]

AirQualityIndex

根据请求参数，此列表最多包含两个空气质量指数：

  • 通用空气质量指数。如果 universalAqi 布尔值设置为 true，则返回此值。
  • 本地空气质量指数。如果指定了 LOCAL_AQI 额外计算，将返回。
pollutants[]

Pollutant

影响请求中所指定位置的污染物列表。注意：只有在请求中指定了以下一个或多个额外计算时，系统才会返回此字段：POLLUTANT_ADDITIONAL_INFO、DOMINANT_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_ARGUMENT 错误。time_range 只能是下列其中一项：
date_time

Timestamp

要返回特定时间点的数据的时间戳。时间戳会四舍五入为前一小时的确切时间。

注意：这只会返回所请求时间戳的每小时数据（即，单个每小时信息元素）。例如，如果发送的 date_time 参数设置为 2023-01-03T11:05:49Z，则发送的请求将向下舍入为 2023-01-03T11:00:00Z。
period

Interval

指示要获取预测数据的开始期和结束期。时间戳会四舍五入到上一个精确的小时。
universal_aqi

bool

可选。如果设置为 true，则通用 AQI 将包含在“指数”中字段（默认值为 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，则返回此值。
  • 本地 AQI。如果指定了 LOCAL_AQI 额外计算，将返回。
pollutants[]

Pollutant

影响请求中指定地点的污染物列表。

注意：只有在请求中指定了以下一个或多个额外计算时，系统才会返回此字段：POLLUTANT_ADDITIONAL_INFO、DOMINANT_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_ARGUMENT 错误。time_range 只能是以下各项之一：time_range 只能是以下各项之一：
date_time

Timestamp

要为其返回历史数据的时间戳。时间戳会四舍五入为前一小时的确切时间。

注意：这只会返回所请求时间戳的每小时数据（即单个每小时信息元素）。例如，如果发送的请求中将 dateTime 参数设置为 2023-01-03T11:05:49Z，则该参数将向下舍入为 2023-01-03T11:00:00Z。

时间戳采用 RFC3339 世界协调时间（UTC，即“祖鲁时”）格式，精确到纳秒，最多九个小数位。示例：“2014-10-02T15:01:23Z”和“2014-10-02T15:01:23.045123456Z”。
hours

int32

从 1 到 720 的数字，表示请求的小时范围。例如：如果值为 48，则会生成过去 48 小时内的数据。
period

Interval

指示要获取历史数据的开始和结束时期。时间戳会四舍五入到上一个精确的小时。
universal_aqi

bool

可选。如果设置为 true，则 Universal AQI 将包含在响应的“indexes”字段中。默认值为 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 世界协调时间 (UTC)（即“祖鲁时”）表示具有纳秒级精度和最多九个小数位。例如：“2014-10-02T15:00:00Z”。
indexes[]

AirQualityIndex

根据请求参数，此列表最多包含两个空气质量指数：

  • 通用空气质量指数。如果 universalAqi 布尔值设置为 true，则返回此值。
  • 本地空气质量指数。如果指定了 LOCAL_AQI 额外计算，将返回。
pollutants[]

Pollutant

影响请求中所指定位置的污染物列表。注意：只有在请求中指定了以下一个或多个额外计算时，系统才会返回此字段：POLLUTANT_ADDITIONAL_INFO、DOMINANT_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_UNSPECIFIED 未指定的浓度单位。
PARTS_PER_BILLION ppb（十亿分之一）浓度单位。
MICROGRAMS_PER_CUBIC_METER “μg/m^3”（微克/立方米）浓度单位。