היסטוריה

נקודת הקצה history מספקת מידע היסטורי שעתי על איכות האוויר במיקום ספציפי, בטווח זמן נתון, עד 30 ימים לכל היותר. אתם יכולים לקבוע איזה מידע על איכות האוויר (AQI) והמאפיינים (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 בצורה הבאה. פרטים נוספים על נתוני התגובות מופיעים במאמר נתוני תגובות.

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

כדי לגשת לדף התוצאות הבא, צריך לשלוח בקשה שנייה לנקודת הקצה (endpoint) 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'