記錄

history 端點會提供特定位置的歷史資料，包括特定時間範圍內每小時的空氣品質資訊，最長可達 30 天。您可以控制系統傳回哪些空氣品質指標和相關資訊 (例如污染物濃度和健康建議)。

您可以使用 history 端點，透過傳送 HTTP POST 要求至下列位置，要求每小時空氣品質記錄：

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

請在 JSON 要求內文中加入要求選項。要求主體包含您要取得每小時空氣品質記錄的位置和時間範圍。也可能包含各種選項，用於控制回應中包含的空氣品質資訊。

您可以透過 APIs 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 回應。如要進一步瞭解回應資料，請參閱「回應資料」。

注意： 根據預設，回應會納入通用空氣品質指數，以及基本空氣品質指數資訊。您可以設定對應的參數，移除或替換空氣品質指數。

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