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:
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'