Package google.maps.airquality.v1

Index

AirQuality

Air quality services.

LookupCurrentConditions

rpc LookupCurrentConditions(LookupCurrentConditionsRequest) returns (LookupCurrentConditionsResponse)

The Current Conditions endpoint provides hourly air quality information in more than 100 countries, up to a 500 x 500 meters resolution. Includes over 70 local indexes and global air quality index and categories.

Authorization scopes

Requires the following OAuth scope:

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

For more information, see the OAuth 2.0 Overview.
LookupForecast

rpc LookupForecast(LookupForecastRequest) returns (LookupForecastResponse)

Returns air quality forecast for a specific location for a given time range.

Authorization scopes

Requires the following OAuth scope:

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

For more information, see the OAuth 2.0 Overview.
LookupHeatmapTile

rpc LookupHeatmapTile(LookupHeatmapTileRequest) returns (HttpBody)

Returns a bytes array containing the data of the tile PNG image.

Authorization scopes

Requires the following OAuth scope:

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

For more information, see the OAuth 2.0 Overview.
LookupHistory

rpc LookupHistory(LookupHistoryRequest) returns (LookupHistoryResponse)

Returns air quality history for a specific location for a given time range.

Authorization scopes

Requires the following OAuth scope:

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

For more information, see the OAuth 2.0 Overview.

AirQualityIndex

The basic object for representing different air quality metrics. When brought together, these metrics provide a snapshot about the current air quality conditions. There are multiple indexes in the world serving different purposes and groups interested in measuring different aspects of air quality.

Fields
code

string

The index's code. This field represents the index for programming purposes by using snake case instead of spaces. Examples: "uaqi", "fra_atmo".
display_name

string

A human readable representation of the index name. Example: "AQI (US)"
aqi_display

string

Textual representation of the index numeric score, that may include prefix or suffix symbols, which usually represents the worst index score. Example: >100 or 10+.

Note: This field should be used when you want to display the index score. For non-numeric indexes, this field is empty.
color

Color

The color used to represent the AQI numeric score.
category

string

Textual classification of the index numeric score interpretation. For example: "Excellent air quality".
dominant_pollutant

string

The chemical symbol of the dominant pollutant. For example: "CO".
aqi

int32

The index's numeric score. Examples: 10, 100.

The value is not normalized and should only be interpreted in the context of its related air-quality index. For non-numeric indexes, this field will not be returned.

Note: This field should be used for calculations, graph display, etc. For displaying the index score, you should use the AQI display field.

ColorPalette

Determines the color palette used for the data provided by the "Universal Air Quality Index" (UAQI). This color palette is relevant just for UAQI, other AQIs have a predetermined color palette that can't be controlled.

Enums
COLOR_PALETTE_UNSPECIFIED The default value. Ignored if passed as a parameter.
RED_GREEN Determines whether to use a red/green palette.
INDIGO_PERSIAN_DARK Determines whether to use a indigo/persian palette (dark theme).
INDIGO_PERSIAN_LIGHT Determines whether to use a indigo/persian palette (light theme).

CustomLocalAqi

Expresses a 'country/region to AQI' relationship. Pairs a country/region with a desired AQI so that air quality data that is required for that country/region will be displayed according to the chosen AQI.

Fields
region_code

string

The country/region requiring the custom AQI. Value should be provided using ISO 3166-1 alpha-2 code.
aqi

string

The AQI to associate the country/region with. Value should be a valid index code.

ExtraComputation

Additional features that can be optionally enabled. Specifying extra computations will result in the relevant elements and fields to be returned in the response.

Enums
EXTRA_COMPUTATION_UNSPECIFIED The default value. The server ignores it if it is passed as a parameter.
LOCAL_AQI

Determines whether to include the local (national) AQI of the requested location (country) in the response.

If specified, the response will contain an 'air_quality_index' data structure with all the relevant data on the location's local AQI.
HEALTH_RECOMMENDATIONS

Determines whether the response will include the health advice and recommended actions for the current AQI conditions.

The recommendations are tailored for the general population and six populations at risk groups with greater sensitivities to pollutants than the general population.

If specified, the health_recommendations field will be populated in the response when the relevant data is available.
POLLUTANT_ADDITIONAL_INFO

Determines whether to include in the response the additional information of each pollutant.

If specified, each air quality index object contained in the 'indexes' field response will include an additional_info field when the data is available.
DOMINANT_POLLUTANT_CONCENTRATION

Determines whether the response would include the concentrations of the dominant pollutants measured according to global and/or local indexes.

If the request specified both the global AQI and the local AQI, there may be up to two pollutant codes returned.

If specified, the dominant pollutant object contained in the 'pollutants' list will include a concentration field when the data is available.
POLLUTANT_CONCENTRATION

Determines whether the response would include the concentrations of all pollutants with available measurements according to global and/or local indexes.

If specified, each pollutant object contained in the 'pollutants' field in the response will include a concentration field when the data is available.

HealthRecommendations

Health recommendations for different population groups in a free text format. The recommendations are derived from their associated air quality conditions.

Fields
general_population

string

No specific sensitivities.
elderly

string

Retirees and people older than the general population.
lung_disease_population

string

Respiratory related problems and asthma suffers.
heart_disease_population

string

Heart and circulatory system diseases.
athletes

string

Sports and other strenuous outdoor activities.
pregnant_women

string

Women at all stages of pregnancy.
children

string

Younger populations including children, toddlers, and babies.

LookupCurrentConditionsRequest

The request definition of the air quality current conditions.

Fields
location

LatLng

Required. The longitude and latitude from which the API looks for air quality current conditions data.
extra_computations[]

ExtraComputation

Optional. Additional features that can be optionally enabled. Specifying extra computations will result in the relevant elements and fields to be returned in the response.
uaqi_color_palette

ColorPalette

Optional. Determines the color palette used for data provided by the 'Universal Air Quality Index' (UAQI). This color palette is relevant just for UAQI, other AQIs have a predetermined color palette that can't be controlled.
custom_local_aqis[]

CustomLocalAqi

Optional. Expresses a 'country/region to AQI' relationship. Pairs a country/region with a desired AQI so that air quality data that is required for that country/region will be displayed according to the chosen AQI. This parameter can be used to specify a non-default AQI for a given country, for example, to get the US EPA index for Canada rather than the default index for Canada.
universal_aqi

bool

Optional. If set to true, the Universal AQI will be included in the 'indexes' field of the response. Default value is true.
language_code

string

Optional. Allows the client to choose the language for the response. If data cannot be provided for that language the API uses the closest match. Allowed values rely on the IETF standard. Default value is en.

LookupCurrentConditionsResponse

Fields
date_time

Timestamp

A rounded down timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. For example: "2014-10-02T15:00:00Z".
region_code

string

The ISO_3166-1 alpha-2 code of the country/region corresponding to the location provided in the request. This field might be omitted from the response if the location provided in the request resides in a disputed territory.
indexes[]

AirQualityIndex

Based on the request parameters, this list will include (up to) two air quality indexes:

  • Universal AQI. Will be returned if the universalAqi boolean is set to true.
  • Local AQI. Will be returned if the LOCAL_AQI extra computation is specified.
pollutants[]

Pollutant

A list of pollutants affecting the location specified in the request. Note: This field will be returned only for requests that specified one or more of the following extra computations: POLLUTANT_ADDITIONAL_INFO, DOMINANT_POLLUTANT_CONCENTRATION, POLLUTANT_CONCENTRATION.
health_recommendations

HealthRecommendations

Health advice and recommended actions related to the reported air quality conditions. Recommendations are tailored differently for populations at risk, groups with greater sensitivities to pollutants, and the general population.

LookupForecastRequest

The request object of the air quality forecast API.

Fields
location

LatLng

Required. The latitude and longitude for which the API looks for air quality data.
extra_computations[]

ExtraComputation

Optional. Additional features that can be optionally enabled. Specifying extra computations will result in the relevant elements and fields to be returned in the response.
uaqi_color_palette

ColorPalette

Optional. Determines the color palette used for data provided by the 'Universal Air Quality Index' (UAQI). This color palette is relevant just for UAQI, other AQIs have a predetermined color palette that can't be controlled.
custom_local_aqis[]

CustomLocalAqi

Optional. Expresses a 'country/region to AQI' relationship. Pairs a country/region with a desired AQI so that air quality data that is required for that country/region will be displayed according to the chosen AQI. This parameter can be used to specify a non-default AQI for a given country, for example, to get the US EPA index for Canada rather than the default index for Canada.
page_size

int32

Optional. The maximum number of hourly info records to return per page (default = 24).
page_token

string

Optional. A page token received from a previous forecast call. It is used to retrieve the subsequent page.
Union field time_range. The time range of the required air quality forecast data. The range must be at least one rounded hour into the future. Failure to specify this field will result in an INVALID_ARGUMENT error. time_range can be only one of the following:
date_time

Timestamp

A timestamp for which to return the data for a specific point in time. The timestamp is rounded to the previous exact hour.

Note: this will return hourly data for the requested timestamp only (i.e. a single hourly info element). For example, a request sent where the date_time parameter is set to 2023-01-03T11:05:49Z will be rounded down to 2023-01-03T11:00:00Z.
period

Interval

Indicates the start and end period for which to get the forecast data. The timestamp is rounded to the previous exact hour.
universal_aqi

bool

Optional. If set to true, the Universal AQI will be included in the 'indexes' field of the response (default = true).
language_code

string

Optional. Allows the client to choose the language for the response. If data cannot be provided for that language the API uses the closest match. Allowed values rely on the IETF standard (default = 'en').

LookupForecastResponse

The response object of the air quality forecast API.

Fields
hourly_forecasts[]

HourlyForecast

Optional. Contains the air quality information for each hour in the requested range. For example, if the request is for 48 hours of forecast there will be 48 elements of hourly forecasts.
region_code

string

Optional. The ISO_3166-1 alpha-2 code of the country/region corresponding to the location provided in the request. This field might be omitted from the response if the location provided in the request resides in a disputed territory.
next_page_token

string

Optional. The token to retrieve the next page.

HourlyForecast

Contains the air quality information for each hour in the requested range. For example, if the request is for 48 hours of forecast there will be 48 elements of hourly forecasts.

Fields
date_time

Timestamp

A rounded down timestamp indicating the time (hour) the data refers to in RFC3339 UTC "Zulu" format. For example: "2014-10-02T15:00:00Z".
indexes[]

AirQualityIndex

Based on the request parameters, this list will include (up to) two air quality indexes:

  • Universal AQI. Will be returned if the universal_aqi boolean is set to true.
  • Local AQI. Will be returned if the LOCAL_AQI extra computation is specified.
pollutants[]

Pollutant

A list of pollutants affecting the location specified in the request.

Note: This field will be returned only for requests that specified one or more of the following extra computations: POLLUTANT_ADDITIONAL_INFO, DOMINANT_POLLUTANT_CONCENTRATION, POLLUTANT_CONCENTRATION.
health_recommendations

HealthRecommendations

Health advice and recommended actions related to the reported air quality conditions. Recommendations are tailored differently for populations at risk, groups with greater sensitivities to pollutants, and the general population.

LookupHeatmapTileRequest

A heatmap tile request.

The structure complies with the standard tile server GET call, i.e. https://airquality.googleapis.com/v1/mapTypes/{map_type}/heatmapTiles/{zoom}/{x}/{y}

Example: https://airquality.googleapis.com/v1/mapTypes/BAQI_INDIGO_PERSIAN/heatmapTiles/1/1/1

Fields
map_type

MapType

Required. The type of the air quality heatmap. Defines the pollutant that the map will graphically represent.

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

Required. The map's zoom level. Defines how large or small the contents of a map appear in a map view.

Zoom level 0 is the entire world in a single tile. Zoom level 1 is the entire world in 4 tiles. Zoom level 2 is the entire world in 16 tiles. Zoom level 16 is the entire world in 65,536 tiles.

Allowed values: 0-16
x

int32

Required. Defines the east-west point in the requested tile.
y

int32

Required. Defines the north-south point in the requested tile.

LookupHistoryRequest

The request object of the air quality history API.

Fields
page_size

int32

Optional. The maximum number of hourly info records to return per page. The default is 72 and the max value is 168 (7 days of data).
page_token

string

Optional. A page token received from a previous history call. It is used to retrieve the subsequent page.

Note that when providing a value for this parameter all other parameters provided must match the call that provided the page token (the previous call).
location

LatLng

Required. The latitude and longitude for which the API looks for air quality history data.
extra_computations[]

ExtraComputation

Optional. Additional features that can be optionally enabled. Specifying extra computations will result in the relevant elements and fields to be returned in the response.
uaqi_color_palette

ColorPalette

Optional. Determines the color palette used for data provided by the 'Universal Air Quality Index' (UAQI). This color palette is relevant just for UAQI, other AQIs have a predetermined color palette that can't be controlled.
custom_local_aqis[]

CustomLocalAqi

Optional. Expresses a 'country/region to AQI' relationship. Pairs a country/region with a desired AQI so that air quality data that is required for that country/region will be displayed according to the chosen AQI. This parameter can be used to specify a non-default AQI for a given country, for example, to get the US EPA index for Canada rather than the default index for Canada.
Union field time_range. The time range of the required air quality data. Failure to specify any time range related field will result in an INVALID_ARGUMENT error. time_range can be only one of the following: time_range can be only one of the following:
date_time

Timestamp

A timestamp for which to return historical data. The timestamp is rounded to the previous exact hour.

Note: this will return hourly data for the requested timestamp only (i.e. a single hourly info element). For example, a request sent where the dateTime parameter is set to 2023-01-03T11:05:49Z will be rounded down to 2023-01-03T11:00:00Z.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
hours

int32

Number from 1 to 720 that indicates the hours range for the request. For example: A value of 48 will yield data from the last 48 hours.
period

Interval

Indicates the start and end period for which to get the historical data. The timestamp is rounded to the previous exact hour.
universal_aqi

bool

Optional. If set to true, the Universal AQI will be included in the 'indexes' field of the response. Default value is true.
language_code

string

Optional. Allows the client to choose the language for the response. If data cannot be provided for that language the API uses the closest match. Allowed values rely on the IETF standard. Default value is en.

LookupHistoryResponse

Fields
hours_info[]

HourInfo

Optional. Contains the air quality information for each hour in the requested range. For example, if the request is for 48 hours of history there will be 48 elements of hourly info.
region_code

string

Optional. The ISO_3166-1 alpha-2 code of the country/region corresponding to the location provided in the request. This field might be omitted from the response if the location provided in the request resides in a disputed territory.
next_page_token

string

Optional. The token to retrieve the next page.

HourInfo

Contains the air quality information for each hour in the requested range. For example, if the request is for 48 hours of history there will be 48 elements of hourly info.

Fields
date_time

Timestamp

A rounded down timestamp indicating the time the data refers to in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. For example: "2014-10-02T15:00:00Z".
indexes[]

AirQualityIndex

Based on the request parameters, this list will include (up to) two air quality indexes:

  • Universal AQI. Will be returned if the universalAqi boolean is set to true.
  • Local AQI. Will be returned if the LOCAL_AQI extra computation is specified.
pollutants[]

Pollutant

A list of pollutants affecting the location specified in the request. Note: This field will be returned only for requests that specified one or more of the following extra computations: POLLUTANT_ADDITIONAL_INFO, DOMINANT_POLLUTANT_CONCENTRATION, POLLUTANT_CONCENTRATION.
health_recommendations

HealthRecommendations

Health advice and recommended actions related to the reported air quality conditions. Recommendations are tailored differently for populations at risk, groups with greater sensitivities to pollutants, and the general population.

MapType

The type of the air quality heatmap. Defines the pollutant that the map will graphically represent.

Enums
MAP_TYPE_UNSPECIFIED The default value. The server ignores it if it is passed as a parameter.
UAQI_RED_GREEN Universal Air Quality Index red-green palette.
UAQI_INDIGO_PERSIAN Universal Air Quality Index indigo-persian palette.
PM25_INDIGO_PERSIAN PM2.5 index indigo-persian palette.
GBR_DEFRA Daily Air Quality Index (UK) color palette.
DEU_UBA German Local Air Quality Index color palette.
CAN_EC Canadian Air Quality Health Index color palette.
FRA_ATMO France Air Quality Index color palette.
US_AQI US Air Quality Index color palette.

Pollutant

Data regarding an air quality pollutant.

Fields
code

string

The pollutant's code name. For example: "so2". A list of all available codes could be found here.
display_name

string

The pollutant's display name. For example: "NOx".
full_name

string

The pollutant's full name. For chemical compounds, this is the IUPAC name. Example: "Sulfur Dioxide".

For more information about the IUPAC names table, see https://iupac.org/what-we-do/periodic-table-of-elements/
concentration

Concentration

The pollutant's concentration level measured by one of the standard air pollutation measure units.
additional_info

AdditionalInfo

Additional information about the pollutant.

AdditionalInfo

The emission sources and health effects of a given pollutant.

Fields
sources

string

Text representing the pollutant's main emission sources.
effects

string

Text representing the pollutant's main health effects.

Concentration

The concentration of a given pollutant in the air.

Fields
units

Unit

Units for measuring this pollutant concentration.
value

float

Value of pollutant concentration.

Unit

Defines the unit used to measure the pollutant's concentration.

Enums
UNIT_UNSPECIFIED Unspecified concentration unit.
PARTS_PER_BILLION The ppb (parts per billion) concentration unit.
MICROGRAMS_PER_CUBIC_METER The "µg/m^3" (micrograms per cubic meter) concentration unit.