التاريخ

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

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

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

أدرِج خيارات الطلب في نص طلب JSON 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'

جرِّبه الآن

يتيح لك مستكشف واجهات برمجة التطبيقات إرسال طلبات نموذجية لتتمكّن من التعرّف على واجهة برمجة التطبيقات وخياراتها.

  1. انقر على رمز واجهة برمجة التطبيقات api على الجانب الأيسر من الصفحة.

  2. يمكنك تعديل معلمات الطلب اختياريًا.

  3. انقر على الزر تنفيذ. في مربّع الحوار، اختَر الحساب الذي تريد استخدامه لإرسال الطلب.

  4. في لوحة مستكشف واجهات برمجة التطبيقات، انقر على رمز ملء الشاشة fullscreen لتوسيع نافذة مستكشف واجهات برمجة التطبيقات.