التوقعات

توفّر نقطة نهاية التوقّعات ما يصل إلى 96 ساعة (4 أيام) من المعلومات المتعلّقة بتوقّعات جودة الهواء كل ساعة في موقع جغرافي معيّن. تتضمن كل توقّعات مؤشرات جودة الهواء كل ساعة بالإضافة إلى معلومات إضافية:

• وقت وتاريخ محدد أو فترة زمنية محددة للتوقعات
• رمز اللغة للحقول المترجَمة
• مؤشر جودة الهواء المحلي أو المخصَّص (AQI)
• اقتراحات متعلقة بالصحة
• الملوّثات السائدة
• تركيز الملوّثات
• معلومات إضافية عن الملوّثات
• حجم صفحة الرد
• لوحة الألوان

لمحة عن طلبات التوقعات

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

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

أدرِج المعلَمات في نص الطلب. يحتوي نص الطلب على الموقع الجغرافي الذي تريد الحصول على معلومات توقّعات جودة الهواء كل ساعة وخيارات متنوعة للتحكّم في المعلومات الإضافية التي يجب تضمينها في الردّ.

لمحة عن الردود على التوقعات

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

مثال على طلب أساسي

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

curl -X POST -d '{
  "location": {
    "latitude": 37.4125333,
    "longitude": -122.0840937
  },
  "dateTime": "2024-02-09T08:00:00Z"
}' \
-H "Content-Type: application/json" \
-H "Accept-Language: *" \
"https://airquality.googleapis.com/v1/forecast:lookup?key=YOUR_API_KEY"

تنشئ المكالمة استجابة JSON التالية.

{
  "hourlyForecasts": [
    {
      "dateTime": "2024-02-09T08:00:00Z",
      "indexes": [
        {
          "code": "uaqi",
          "displayName": "Universal AQI",
          "aqi": 80,
          "aqiDisplay": "80",
          "color": {
            "red": 0.34509805,
            "green": 0.74509805,
            "blue": 0.20784314
          },
          "category": "Excellent air quality",
          "dominantPollutant": "pm25"
        }
      ]
    }
  ],
  "regionCode": "us"
}

مثال على طلب يتضمّن معلَمات متعددة

توضح التعليمة البرمجية التالية كيفية إنشاء نص طلب باستخدام معلَمات متعددة. في هذا المثال، يمكنك تحديد ما يلي:

• الموقع الجغرافي
• الفترة الزمنية التي يتم خلالها عرض معلومات توقّعات جودة الهواء
• رمز اللغة
• العمليات الحسابية الإضافية (مثل الاقتراحات المتعلقة بالصحة وتركيز الملوّثات السائدة ومعلومات إضافية عن الملوّثات)
• لوحة الألوان

curl -X POST -d '{
    "pageSize": "10",
    "universalAqi": "true",
    "location": {
        "latitude": "40.741895",
        "longitude": "-73.989308"
    },
    "period": {
        "startTime": "2024-02-27T13:58:14+02:00",
        "endTime": "2024-02-28T16:58:14+02:00"
    },
    "languageCode": "en",
    "extraComputations": [
        "HEALTH_RECOMMENDATIONS",
        "DOMINANT_POLLUTANT_CONCENTRATION",
        "POLLUTANT_ADDITIONAL_INFO"
    ],
    "uaqiColorPalette": "RED_GREEN"
}' \
-H "Content-Type: application/json" \
-H "Accept-Language: *" \
"https://airquality.googleapis.com/v1/forecast:lookup?key=YOUR_API_KEY"

تنشئ المكالمة استجابة JSON التالية.

{
  {
  "hourlyForecasts": [
    {
      "dateTime": "2024-02-27T11:00:00Z",
      "indexes": [
        {
          "code": "uaqi",
          "displayName": "Universal AQI",
          "aqi": 75,
          "aqiDisplay": "75",
          "color": {
            "red": 0.43137255,
            "green": 0.7764706,
            "blue": 0.20392157
          },
          "category": "Good air quality",
          "dominantPollutant": "pm25"
        }
      ],
      "pollutants": [
        {
          "code": "pm25",
          "displayName": "PM2.5",
          "fullName": "Fine particulate matter (\u003c2.5µm)",
          "concentration": {
            "value": 15.1,
            "units": "MICROGRAMS_PER_CUBIC_METER"
          },
          "additionalInfo": {
            "sources": "...",
            "effects": "..."
          }
        }
      ],
      "healthRecommendations": {
        "generalPopulation": "...",
        "lungDiseasePopulation": "...",
        "heartDiseasePopulation": "...",
        "athletes": "...",
        "pregnantWomen": "..."
      }
    },
    {
      "dateTime": "2024-02-27T12:00:00Z",
      "indexes": [
        {
          "code": "uaqi",
          "displayName": "Universal AQI",
          "aqi": 67,
          "aqiDisplay": "67",
          "color": {
            "red": 0.5882353,
            "green": 0.8392157,
            "blue": 0.16862746
          },
          "category": "Good air quality",
          "dominantPollutant": "pm25"
        }
      ],
      "pollutants": [
        {
          "code": "pm25",
          "displayName": "PM2.5",
          "fullName": "Fine particulate matter (\u003c2.5µm)",
          "concentration": {
            "value": 19.96,
            "units": "MICROGRAMS_PER_CUBIC_METER"
          },
          "additionalInfo": {
            "sources": "...",
            "effects": "..."
          }
        }
      ],
      "healthRecommendations": {
        "generalPopulation": "...",
        "lungDiseasePopulation": "...",
        "heartDiseasePopulation": "...",
        "athletes": "...",
        "pregnantWomen": "...",
        "children": "..."
      }
    },
    /.../
  ]
  }
  "regionCode": "us",
  "nextPageToken": "CjMKEglwCFVq9l5EQBH0aoDSUH9SwBoQCgYI1pDirgYSBgiGiOiuBiABKgMCBAMyAmVuOAEQGA=="
}

لعرض الصفحة التالية من معلومات التوقّعات، مرِّر علامة nextPageToken الظاهرة في نهاية نص الاستجابة:

curl -X POST -d '{
    "universalAqi": "true",
    "location": {
        "latitude": "40.741895",
        "longitude": "-73.989308"
    },
    "period": {
        "startTime": "2024-02-27T13:58:14+02:00",
        "endTime": "2024-02-28T16:58:14+02:00"
    },
    "languageCode": "en",
    "extraComputations": [
        "HEALTH_RECOMMENDATIONS",
        "DOMINANT_POLLUTANT_CONCENTRATION",
        "POLLUTANT_ADDITIONAL_INFO"
    ],
    "uaqiColorPalette": "RED_GREEN",
    "pageToken": "CjMKEglwCFVq9l5EQBH0aoDSUH9SwBoQCgYI1pDirgYSBgiGiOiuBiABKgMCBAMyAmVuOAEQGA=="
}' \
-H "Content-Type: application/json" \
-H "Accept-Language: *" \
"https://airquality.googleapis.com/v1/forecast:lookup?key=YOUR_API_KEY"

يؤدي ذلك إلى عرض الصفحة التالية لمعلومات التوقعات:

{
  "hourlyForecasts": [
    {
      "dateTime": "2024-02-27T21:00:00Z",
      "indexes": [
        {
          "code": "uaqi",
          "displayName": "Universal AQI",
          "aqi": 74,
          "aqiDisplay": "74",
          "color": {
            "red": 0.44705883,
            "green": 0.78431374,
            "blue": 0.2
          },
          "category": "Good air quality",
          "dominantPollutant": "o3"
        }
      ],
      "pollutants": [
        {
          "code": "o3",
          "displayName": "O3",
          "fullName": "Ozone",
          "concentration": {
            "value": 32.07,
            "units": "PARTS_PER_BILLION"
          },
          "additionalInfo": {
            "sources": "...",
            "effects": "..."
          }
        }
      ],
      "healthRecommendations": {
        "generalPopulation": "...",
        "elderly": "...",
        "lungDiseasePopulation": "...",
        "heartDiseasePopulation": "...",
        "athletes": "...",
        "pregnantWomen": "...",
        "children": "..."
      }
    },
    {
      "dateTime": "2024-02-27T22:00:00Z",
      "indexes": [
        {
          "code": "uaqi",
          "displayName": "Universal AQI",
          "aqi": 75,
          "aqiDisplay": "75",
          "color": {
            "red": 0.43137255,
            "green": 0.7764706,
            "blue": 0.20392157
          },
          "category": "Good air quality",
          "dominantPollutant": "o3"
        }
      ],
      "pollutants": [
        {
          "code": "o3",
          "displayName": "O3",
          "fullName": "Ozone",
          "concentration": {
            "value": 30.94,
            "units": "PARTS_PER_BILLION"
          },
          "additionalInfo": {
            "sources": "...",
            "effects": "..."
          }
        }
      ],
      "healthRecommendations": {
        "generalPopulation": "...",
        "lungDiseasePopulation": "...",
        "heartDiseasePopulation": "...",
        "athletes": "...",
        "pregnantWomen": "...",
        "children": "..."
      }
    },
    /.../
  ]
  "regionCode": "us"
}