Method: history.lookup

返回指定时间范围内特定地点的空气质量历史记录。

HTTP 请求

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

网址采用 gRPC 转码语法。

请求正文

请求正文中包含结构如下的数据:

JSON 表示法
{
  "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
}
字段
pageSize

integer

可选。每页返回的每小时信息记录数量上限。默认值为 72,最大值为 168(7 天的数据)。

pageToken

string

可选。从之前的历史记录调用收到的页面令牌。它用于检索后续页面。

请注意,在为此参数提供值时,提供的所有其他参数必须与提供页面令牌的调用(上一个调用)匹配。

location

object (LatLng)

必需。API 用于查找空气质量历史数据的纬度和经度。

extraComputations[]

enum (ExtraComputation)

可选。可以选择启用的其他功能。指定额外的计算数量会导致响应中返回相关元素和字段。

uaqiColorPalette

enum (ColorPalette)

可选。确定“通用空气质量指数”(UAQI) 所提供数据所使用的调色板。此调色板只与 UAQI 相关,其他 AQI 有无法控制的预设调色板。

customLocalAqis[]

object (CustomLocalAqi)

可选。表示“国家/地区与 AQI”的关系。将某个国家/地区与所需的 AQI 配对,以便根据所选 AQI 显示该国家/地区所需的空气质量数据。此参数可用于指定给定国家/地区的非默认 AQI,例如,获取加拿大的 US EPA 指数,而不是加拿大的默认指数。

联合字段 time_range。所需空气质量数据的时间范围。如果没有指定任何与时间范围相关的字段,将导致 INVALID_STRING 错误。time_range 只能是以下其中一项:time_range 只能是以下其中一项:
dateTime

string (Timestamp format)

要为其返回历史数据的时间戳。时间戳会四舍五入到上一个精确的小时。

注意:这将仅返回所请求时间戳的每小时数据(即单个每小时信息元素)。例如,如果发送的 dateTime 参数设置为 2023-01-03T11:05:49Z,则请求将向下舍入为 2023-01-03T11:00:00Z。

时间戳,采用 RFC3339 世界协调时间 (UTC)(即“祖鲁时”)格式,具有纳秒级分辨率,最多包含九个小数位。示例:“2014-10-02T15:01:23Z”和“2014-10-02T15:01:23.045123456Z”。

hours

integer

1 到 720 之间的数字,表示请求的小时范围。例如:值为 48 将生成过去 48 小时的数据。

period

object (Interval)

指示要获取其历史数据的开始和结束时间段。时间戳会四舍五入到上一个精确的小时。

universalAqi

boolean

可选。如果设置为 true,Universal AQI 将包含在响应的“indexes”字段中。默认值为 true。

languageCode

string

可选。允许客户端选择响应的语言。如果无法针对该语言提供数据,API 会使用最接近的匹配项。允许使用的值取决于 IETF 标准。默认值为 en。

响应正文

如果成功,响应正文将包含结构如下的数据:

JSON 表示法
{
  "hoursInfo": [
    {
      object (HourInfo)
    }
  ],
  "regionCode": string,
  "nextPageToken": string
}
字段
hoursInfo[]

object (HourInfo)

可选。包含所请求范围内每小时的空气质量信息。例如,如果请求获取的是 48 小时的历史记录,那么会有 48 个小时信息元素。

regionCode

string

可选。与请求中提供的位置对应的国家/地区的 ISO_3166-1 alpha-2 代码。如果请求中提供的位置位于有争议的地区,响应中可能会省略此字段。

nextPageToken

string

可选。用于检索下一页的令牌。

授权范围

需要以下 OAuth 作用域:

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

有关详情,请参阅 OAuth 2.0 概览

间隔时间

表示时间间隔,编码为时间戳开始(含)和时间戳结束(不含时间戳)。

起始值必须小于或等于结束值。如果开始时间等于结束时间,则间隔为空(不匹配时间)。如果未指定 start 和 end,则任何时间间隔都相同。

JSON 表示法
{
  "startTime": string,
  "endTime": string
}
字段
startTime

string (Timestamp format)

可选。间隔的开始(含)。

如果指定,则与此间隔时间匹配的时间戳必须与开始时间相同或晚于开始时间。

endTime

string (Timestamp format)

可选。间隔的结束(不含独占模式)。

如果指定,则与此间隔时间匹配的时间戳必须位于结束日期之前。

HourInfo

包含所请求范围内每小时的空气质量信息。例如,如果请求获取的是 48 小时的历史记录,那么会有 48 个小时信息元素。

JSON 表示法
{
  "dateTime": string,
  "indexes": [
    {
      object (AirQualityIndex)
    }
  ],
  "pollutants": [
    {
      object (Pollutant)
    }
  ],
  "healthRecommendations": {
    object (HealthRecommendations)
  }
}
字段
dateTime

string (Timestamp format)

这是一个向下舍入的时间戳,以 RFC3339 世界协调时间 (UTC)(即“祖鲁时”)格式表示数据所指时间,分辨率为纳秒,最多包含九个小数位。例如:“2014-10-02T15:00:00Z”。

indexes[]

object (AirQualityIndex)

根据请求参数,此列表将包括(最多)两个空气质量指数:

  • 通用 AQI。如果 universalAqi 布尔值设置为 true,则返回此值。
  • 本地空气质量指数。如果指定了 LOCAL_AQI 额外计算,则返回此值。
pollutants[]

object (Pollutant)

影响请求中指定位置的污染物列表。注意:只有指定了以下一项或多项额外计算的请求才会返回此字段:POLLUTANT_ADDITIONAL_INFO、DOMINANT_POLLUTANT_CONCENTRATION、POLLUTANT_CONCENTRATION。

healthRecommendations

object (HealthRecommendations)

与报告的空气质量状况相关的健康建议和推荐措施。针对风险人群、对污染物更敏感的群体以及总体人群量身定制的建议有所不同。