تاریخ

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

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

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

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

مرورگر APIها به شما امکان می‌دهد درخواست‌های زنده ارسال کنید تا بتوانید با API و گزینه‌های API آشنا شوید:

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

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

کد زیر نحوه ساخت بدنه درخواست برای یک درخواست تاریخچه یک ساعته با استفاده از متد 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 زیر را تولید می‌کند. برای جزئیات بیشتر در مورد داده‌های پاسخ، به Response data مراجعه کنید.

{
    "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 به شکل زیر تولید می‌کنند. برای جزئیات بیشتر در مورد داده‌های پاسخ، به Response data مراجعه کنید.

هر دو فراخوانی فوق، داده‌های کیفیت هوا را برای چهار ساعت درخواست می‌کنند. با این حال، از آنجا که شما در درخواست، ویژگی 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ها به شما امکان می‌دهد درخواست‌های نمونه ایجاد کنید تا با API و گزینه‌های API آشنا شوید.

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

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

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

  4. در پنل APIs Explorer، آیکون تمام صفحه را در حالت تمام صفحه انتخاب کنید تا پنجره APIs Explorer باز شود.