Histori

Endpoint history memberikan informasi kualitas udara per jam historis untuk lokasi tertentu, untuk rentang waktu tertentu, hingga maksimum 30 hari. Anda dapat mengontrol AQI dan informasi terkait yang ditampilkan (seperti tingkat konsentrasi polutan dan rekomendasi kesehatan).

Anda dapat meminta histori kualitas udara per jam menggunakan endpoint history dengan mengirimkan permintaan POST HTTP ke:

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

Sertakan opsi permintaan Anda dalam isi permintaan JSON. Isi permintaan berisi lokasi dan rentang waktu yang ingin Anda dapatkan histori kualitas udara per jamnya. API ini juga dapat menyertakan berbagai opsi untuk mengontrol informasi kualitas udara yang akan disertakan dalam respons.

APIs Explorer memungkinkan Anda membuat permintaan langsung sehingga Anda dapat memahami API dan opsi API:

Cobalah!

Contoh permintaan satu jam

Isi permintaan satu jam

Kode berikut menunjukkan cara membuat isi permintaan untuk permintaan histori satu jam menggunakan metode history. Dalam contoh ini, Anda menetapkan lokasi dan stempel waktu sebelumnya.

Catatan: Pastikan parameter dateTime menentukan jangka waktu dalam 30 hari terakhir.

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'

Respons dalam satu jam

Panggilan di atas menghasilkan respons JSON berikut. Untuk mengetahui detail selengkapnya tentang data respons, lihat Data respons.

Catatan: Secara default, respons menyertakan AQI Universal dengan informasi AQI dasar. AQI dapat dihapus atau diganti dengan AQI lain dengan menetapkan parameter yang sesuai.

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

Catatan: Jika nilai kolom color adalah 0, kolom tersebut akan dihilangkan dari respons.

Contoh permintaan rentang waktu

Permintaan rentang waktu

Kode berikut menunjukkan cara membuat isi permintaan untuk history yang menampilkan beberapa data kualitas udara per jam historis.

Anda dapat meminta beberapa data dengan menentukan rentang waktu, yang berarti stempel waktu mulai dan berakhir, atau dengan menentukan jumlah jam mundur dari waktu saat ini.

Catatan: Hasil ditampilkan dalam halaman, dengan hasil terbaru ditampilkan di halaman pertama. Gunakan properti pageSize untuk mengontrol jumlah maksimum hasil per halaman. Jika diperlukan lebih dari satu halaman untuk mengambil semua hasil, setiap halaman akan menyertakan properti nextPageToken yang berisi token yang Anda gunakan untuk mengambil halaman berikutnya.

Pada contoh di bawah, karena Anda menetapkan ukuran halaman ke 2, permintaan Anda untuk histori kualitas udara selama empat jam ditampilkan dalam dua halaman, dengan setiap halaman berisi data selama dua jam.

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'

Anda dapat membuat permintaan serupa dengan meneruskan stempel waktu mulai dan akhir:

Catatan: Pastikan parameter startTime dan endTime menentukan jangka waktu dalam 30 hari terakhir.

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'

Respons rentang waktu

Panggilan di atas menghasilkan respons JSON dalam bentuk di bawah. Untuk mengetahui detail selengkapnya tentang data respons, lihat Data respons.

Kedua panggilan di atas meminta data kualitas udara selama empat jam. Namun, karena Anda menetapkan properti pageSize ke 2 dalam permintaan, respons hanya menyertakan hasil untuk dua jam terakhir.

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

Perhatikan bahwa respons juga menyertakan properti nextPageToken. Gunakan properti ini untuk mengakses halaman hasil berikutnya, yang berisi data dua jam berikutnya.

Untuk mengakses halaman hasil berikutnya, buat permintaan kedua ke endpoint history, tetapi kali ini tetapkan properti pageToken ke nilai nextPageToken dari respons pertama.

Catatan: Saat meneruskan properti pageToken untuk mengakses halaman data berikutnya, semua parameter permintaan lainnya harus cocok dengan panggilan asli yang menyediakan token halaman.

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'

Cobalah!

APIs Explorer memungkinkan Anda membuat contoh permintaan sehingga Anda dapat memahami API dan opsi API.

1. Pilih ikon API api di sisi kanan halaman.

2. Edit parameter permintaan jika perlu.

3. Pilih tombol Execute. Dalam dialog, pilih akun yang ingin Anda gunakan untuk membuat permintaan.

4. Di panel APIs Explorer, pilih ikon layar penuh fullscreen untuk meluaskan jendela APIs Explorer.