Method: history.lookup

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

HTTP request

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

The URL uses gRPC Transcoding syntax.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "pageSize": integer,
  "pageToken": string,
  "location": {
    object (LatLng)
  },
  "extraComputations": [
    enum (ExtraComputation)
  ],
  "uaqiColorPalette": enum (ColorPalette),
  "customLocalAqis": [
    {
      object (CustomLocalAqi)
    }
  ],

  // Union field time_range can be only one of the following:
  "dateTime": string,
  "hours": integer,
  "period": {
    object (Interval)
  }
  // End of list of possible types for union field time_range.
  "universalAqi": boolean,
  "languageCode": string
}
Fields
pageSize

integer

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

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

object (LatLng)

Required. The latitude and longitude for which the API looks for air quality history 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.
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:
dateTime

string (Timestamp format)

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

integer

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

object (Interval)

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

boolean

Optional. If set to true, the Universal AQI will be included in the 'indexes' field of the response. Default value is 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 value is en.

Response body

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

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

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

Interval

Represents a time interval, encoded as a Timestamp start (inclusive) and a Timestamp end (exclusive).

The start must be less than or equal to the end. When the start equals the end, the interval is empty (matches no time). When both start and end are unspecified, the interval matches any time.

JSON representation 
{
  "startTime": string,
  "endTime": string
}
Fields
startTime

string (Timestamp format)

Optional. Inclusive start of the interval.

If specified, a Timestamp matching this interval will have to be the same or after the start.
endTime

string (Timestamp format)

Optional. Exclusive end of the interval.

If specified, a Timestamp matching this interval will have to be before the end.

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.

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

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.