היסטוריה

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

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

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

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

דוגמה לבקשה בשעה אחת

גוף הבקשה לשעה אחת

הקוד הבא מראה איך ליצור גוף בקשה לבקשת היסטוריה של שעה אחת, באמצעות השיטה 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'