היסטוריה

נקודת הקצה history מספקת מידע היסטורי על איכות האוויר לפי שעה במיקום ספציפי, לטווח זמן נתון, עד 30 יום לכל היותר. אתם יכולים לקבוע אילו מדדי AQI ומידע רלוונטי יוצגו (למשל רמת הריכוז של המזהמים והמלצות לבריאות).

אפשר לבקש היסטוריה של איכות האוויר השעתית באמצעות נקודת הקצה history, על ידי שליחת בקשת HTTP POST אל:

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

אפשרויות הבקשה צריכות להיכלל בגוף הבקשה ב-JSON. גוף הבקשה מכיל את המיקום ואת טווח הזמן שלגביהם רוצים לקבל את היסטוריית איכות האוויר השעתית. יכול להיות שהיא תכלול גם אפשרויות שונות לשלוט במידע על איכות האוויר שייכלל בתשובה.

ב-APIs Explorer אפשר לשלוח בקשות בזמן אמת כדי להתנסות ב-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 הבאה. פרטים נוספים על נתוני התגובה זמינים במאמר נתוני תגובה.

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