Package google.maps.airquality.v1

索引

AirQuality

空气质量服务。

LookupCurrentConditions

rpc LookupCurrentConditions(LookupCurrentConditionsRequest) returns (LookupCurrentConditionsResponse)

“当前条件”端点提供每小时 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

决定是否在响应中添加每种污染物的额外信息。

如果指定，则在数据可用时，“indexes”字段响应中包含的每个空气质量指数对象都会包含一个 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

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

  • 通用 AQI。如果 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_STRING 错误。time_range 只能是下列其中一项：
date_time

Timestamp

要返回特定时间点的数据的时间戳。时间戳会四舍五入到上一个精确小时。

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

Interval

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

bool

可选。如果设置为 true，则 Universal 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)（即“祖鲁时”）格式。例如：“2014-10-02T15:00:00Z”。
indexes[]

AirQualityIndex

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

  • 通用 AQI。如果 universal_aqi 布尔值设置为 true，则返回此值。
  • 本地空气质量指数。如果指定了 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

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

  • 通用 AQI。如果 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”（每立方米微克）浓度单位。