历史记录

history 端点可提供特定地点在给定时间范围（最长 30 天）内的每小时历史空气质量信息。您可以控制系统返回哪些 AQI 和相关信息（例如污染物浓度水平和健康建议）。

您可以使用 history 端点请求每小时空气质量历史记录，方法是向以下网址发送 HTTP POST 请求：

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

在 JSON 请求正文中添加请求选项。请求正文包含您要获取小时空气质量历史记录的位置和时间范围。它可能还包含各种选项，用于控制在回答中包含哪些空气质量信息。

借助 API Explorer，您可以发出实时请求，以便熟悉 API 和 API 选项：

试试看！

单小时请求示例

单小时请求正文

以下代码展示了如何使用 history 方法为单小时历史记录请求构建请求正文。在此示例中，您需要设置位置和过去的时间戳。

注意 ：请确保 dateTime 参数指定的是过去 30 天内的某个时间段。

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'

一小时内回复

上述调用会生成以下 JSON 响应。如需详细了解响应数据，请参阅响应数据。

注意 ：默认情况下，响应包含包含基本 AQI 信息的通用 AQI。您可以通过设置相应参数来移除 AQI 或将其替换为其他 AQI。

{
    "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"
}

注意： 如果 color 字段值为 0，则响应中将不会出现该字段。

时间范围请求示例

时间范围请求

以下代码展示了如何为 history 构建请求正文，该请求会返回多个历史小时空气质量记录。

您可以通过指定时间范围（即开始时间戳和结束时间戳）或指定距离当前时间的小时数来请求多个记录。

注意： 系统会以页面的形式返回结果，最新的结果会显示在第一页中。使用 pageSize 属性控制每页的结果数上限。如果需要多个页面才能检索到所有结果，则每个页面都包含 nextPageToken 属性，其中包含用于检索后续页面的令牌。

在以下示例中，由于您将页面大小设置为 2，因此系统会将您请求的四小时空气质量历史记录分为两页返回，每页包含两个小时的数据。

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'

您可以通过传递开始时间戳和结束时间戳来发出类似的请求：

注意 ：请确保 startTime 和 endTime 参数指定的是过去 30 天内的某个时间段。

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'

时间范围响应

上述调用会生成以下形式的 JSON 响应。如需详细了解响应数据，请参阅响应数据。

上述两个调用都请求四小时的空气质量数据。不过，由于您在请求中将 pageSize 属性设为了 2，因此响应中仅包含最近两个小时内的结果。

{
    "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"
}

请注意，响应还包含 nextPageToken 属性。使用此属性可访问下一页结果，其中包含接下来两小时的数据。

如需访问下一页结果，请再次向 history 端点发出请求，但这次将 pageToken 属性设置为第一个响应中的 nextPageToken 值。

注意 ：传递 pageToken 属性以访问后续数据页时，所有其他请求参数都必须与提供页面令牌的原始调用一致。

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'