التاريخ

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

يمكنك طلب سجلّ جودة الهواء كل ساعة باستخدام نقطة النهاية history من خلال إرسال طلب POST عبر HTTP إلى:

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'