History

The history endpoint provides historical hourly air quality information for a specific location, for a given time range, up to a maximum of 30 days. You can control the which AQIs and pertinent information are returned (such as pollutants concentration level and health recommendations).

You can request history of hourly air quality using the history endpoint by sending an HTTP POST request to:

https://airquality.googleapis.com/v1/history:lookup?key=YOUR_API_KEY

Include your request options in the JSON request body. The request body contains the location and the time range for which you would like to get the hourly air quality history. It may also include various options to control what air quality information to include in the response.

The APIs Explorer lets you make live requests so that you can get familiar with the API and the API options:

Try it!

Example of a single hour request

Single hour request body

The following code shows how to construct a request body for a single hour history request using history method. In this example, you set the location and the past timestamp.

curl -X POST -d '{
  "dateTime": "2023-06-26T15:01:23Z",
  "location": {
    "latitude": 37.419734,
    "longitude": -122.0827784
  }
}' \
-H 'Content-Type: application/json' \
'https://airquality.googleapis.com/v1/history:lookup?key=YOUR_API_KEY'

Single hour response

The call above generates the following JSON response. For more details about the response data, see Response data.

{
    "hoursInfo": [
        {
            "dateTime": "2023-06-26T15:00:00Z",
            "indexes": [
                {
                    "code": "uaqi",
                    "displayName": "Universal AQI",
                    "aqi": 73,
                    "aqiDisplay": "73",
                    "color": {
                        "red": 118,
                        "green": 202,
                        "blue": 51,
                        "alpha": 255
                    },
                    "category": "Good air quality",
                    "dominantPollutant": "pm10"
                }
            ]
        }
    ],
    "regionCode": "us"
}

Example of time range request

Time range request

The following code shows how to construct a request body for a history which returns multiple records of historical hourly air quality.

You can requesting multiple records by specifying a time range, meaning a start and end timestamp, or by specifying the number of hours back from the current time.

In the example below, because you set the page size to 2, your request for four hours of air quality history is returned in two pages, where each page contains two hours of data.

curl -X POST -d '{
  "hours": 4,
  "pageSize": 2,
  "pageToken":"",
  "location": {
    "latitude": 37.419734,
    "longitude": -122.0827784
  }
}' \
-H 'Content-Type: application/json' \
'https://airquality.googleapis.com/v1/history:lookup?key=YOUR_API_KEY'

You can make a similar request by passing the start and end timestamps:

curl -X POST -d '{
  "period": {
      "startTime":"2023-06-15T08:00:00Z",
      "endTime":"2023-06-15T12:00:00Z"
  },
  "pageSize": 2,
  "pageToken":"",
  "location": {
    "latitude": 37.419734,
    "longitude": -122.0827784
  }
}' \
-H 'Content-Type: application/json' \
'https://airquality.googleapis.com/v1/history:lookup?key=YOUR_API_KEY'

Time range response

The calls above generates a JSON response in the form below. For more details about the response data, see Response data.

Both calls above request four hours air quality data. However, because you set the pageSize property to 2 in the request, the response only includes results for the most recent two hours.

{
    "hoursInfo": [
        {
            "dateTime": "2023-06-15T11:00:00Z",
            "indexes": [
                {
                    "code": "uaqi",
                    "displayName": "Universal AQI",
                    "aqi": 83,
                    "aqiDisplay": "83",
                    "color": {
                        "red": 74,
                        "green": 185,
                        "blue": 54,
                        "alpha": 255
                    },
                    "category": "Excellent air quality",
                    "dominantPollutant": "o3"
                }
            ]
        },
        {
            "dateTime": "2023-06-15T10:00:00Z",
            "indexes": [
                {
                    "code": "uaqi",
                    "displayName": "Universal AQI",
                    "aqi": 89,
                    "aqiDisplay": "89",
                    "color": {
                        "red": 48,
                        "green": 175,
                        "blue": 55,
                        "alpha": 255
                    },
                    "category": "Excellent air quality",
                    "dominantPollutant": "o3"
                }
            ]
        }
    ],
    "regionCode": "us",
    "nextPageToken": "ChYaEgl3gv3XubVCQBEsNMY9TTdUMTE6MDA6MDA"
}

Notice that the response also includes the nextPageToken property. Use this property to access the next page of the results, which contains the next two hours of data.

To access the next page of results, make a second request to the history endpoint, but this time set the pageToken property to the value of nextPageToken from the first response.

curl -X POST -d '{
  "hours": 4,
  "pageSize": 2,
  "pageToken":"ChYaEgl3gv3XubVCQBEsNMY9TTdUMTE6MDA6MDA",
  "location": {
    "latitude": 37.419734,
    "longitude": -122.0827784
  }
}' \
-H 'Content-Type: application/json' \
'https://airquality.googleapis.com/v1/history:lookup?key=YOUR_API_KEY'