التاريخ

توفّر نقطة النهاية 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، يتم عرض طلبك لمدّة 4 ساعات من سجلّ جودة الهواء في صفحتين، حيث تحتوي كل صفحة على ساعتَين من البيانات.

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'