التاريخ

توفّر نقطة النهاية history معلومات سابقة حول جودة الهواء كل ساعة في موقع جغرافي محدّد ولمدة زمنية تصل إلى 30 يومًا كحد أقصى. يمكنك التحكّم في مؤشرات جودة الهواء والمعلومات ذات الصلة التي يتم عرضها (مثل مستوى تركيز الملوّثات واقتراحات الصحة).

يمكنك طلب سجلّ جودة الهواء كل ساعة من خلال نقطة النهاية 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'