Method: forecast.lookup

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

HTTP request

POST https://airquality.googleapis.com/v1/forecast:lookup

The URL uses gRPC Transcoding syntax.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "location": {
    object (LatLng)
  },
  "extraComputations": [
    enum (ExtraComputation)
  ],
  "uaqiColorPalette": enum (ColorPalette),
  "customLocalAqis": [
    {
      object (CustomLocalAqi)
    }
  ],
  "pageSize": integer,
  "pageToken": string,
  "dateTime": string,
  "period": {
    object (Interval)
  }
  // End of list of possible types for union field time_range.
  "universalAqi": boolean,
  "languageCode": string
}
Fields
location

object (LatLng)

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

enum (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.
uaqiColorPalette

enum (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.
customLocalAqis[]

object (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.
pageSize

integer

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

string

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

string (Timestamp format)

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

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.

Note: Either dateTime or startTime and endTime can be used in a request.
period

object (Interval)

Indicates the startTime and endTime period for which to get the forecast data. The endTime is inclusive. The timestamp is rounded to the previous exact hour.

Note: Either dateTime or startTime and endTime can be used in a request.
universalAqi

boolean

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

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').

Response body

The response object of the air quality forecast API.

If successful, the response body contains data with the following structure:

JSON representation 
{
  "hourlyForecasts": [
    {
      object (HourlyForecast)
    }
  ],
  "regionCode": string,
  "nextPageToken": string
}
Fields
hourlyForecasts[]

object (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.
regionCode

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.
nextPageToken

string

Optional. The token to retrieve the next page.

Authorization scopes

Requires the following OAuth scope:

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

For more information, see the OAuth 2.0 Overview.

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.

JSON representation 
{
  "dateTime": string,
  "indexes": [
    {
      object (AirQualityIndex)
    }
  ],
  "pollutants": [
    {
      object (Pollutant)
    }
  ],
  "healthRecommendations": {
    object (HealthRecommendations)
  }
}
Fields
dateTime

string (Timestamp format)

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[]

object (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[]

object (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.
healthRecommendations

object (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.