سابقه

نقطه پایانی history اطلاعات ساعتی سابقه کیفیت هوا را برای مکانی خاص، در محدوده زمانی مشخص، و حداکثر تا ۳۰ روز ارائه می‌دهد. می‌توانید کنترل کنید کدام AQI و اطلاعات مربوطه (مثل سطح غلظت آلاینده‌ها و توصیه‌های بهداشتی) برگردانده شود.

می‌توانید سابقه کیفیت هوای ساعتی را بااستفاده از نقطه پایانی history با ارسال درخواست HTTP POST به نشانی زیر درخواست کنید:

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

گزینه‌های درخواستتان را در بدنه درخواست JSON بگنجانید. بدنه درخواست حاوی مکان و محدوده زمانی است که می‌خواهید سابقه ساعتی کیفیت هوا را برای آن دریافت کنید. همچنین ممکن است شامل گزینه‌های مختلفی برای کنترل اطلاعات کیفیت هوایی باشد که باید در پاسخ گنجانده شود.

‫APIs Explorer به شما امکان می‌دهد درخواست‌های مستقیم ارسال کنید تا بتوانید با «میانای برنامه‌سازی کاربردی» و گزینه‌های آن آشنا شوید:

نمونه‌ای از درخواست یک ساعت

متن درخواست ساعت تکی

کد زیر نحوه ساختن بدنه درخواست برای درخواست سابقه یک ساعت را بااستفاده از روش history نشان می‌دهد. در این مثال، مکان و مُهر زمان گذشته را تنظیم می‌کنید.

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

نمونه درخواست محدوده زمانی

درخواست محدوده زمانی

کد زیر نحوه ساختن بدنه درخواست برای history را نشان می‌دهد که چندین سوابق کیفیت هوای ساعتی را برمی‌گرداند.

می‌توانید با مشخص کردن محدوده زمانی، یعنی مُهر زمان شروع و پایان، یا با مشخص کردن تعداد ساعت‌های گذشته از زمان فعلی، چندین سابقه را درخواست کنید.

در مثال زیر، چون اندازه صفحه را روی 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'

با ارسال مُهرهای زمان شروع و پایان می‌توانید درخواست مشابهی ارائه دهید:

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 از پاسخ اول تنظیم کنید.

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'

امتحان کنید!

با API Explorer می‌توانید درخواست‌های نمونه ایجاد کنید تا با API و گزینه‌های API آشنا شوید.

  1. نماد API api را در سمت راست صفحه انتخاب کنید.

  2. درصورت تمایل، پارامترهای درخواست را ویرایش کنید.

  3. دکمه اجرا را انتخاب کنید. در کادر گفتگو، حسابی را که می‌خواهید برای درخواست استفاده شود انتخاب کنید.

  4. در پانل «کاوشگر API»، نماد تمام‌صفحه تمام‌صفحه را انتخاب کنید تا پنجره «کاوشگر API» ازهم باز شود.