التوقعات

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

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

تتيح لك أداة "مستكشف واجهات برمجة التطبيقات" إجراء طلبات مباشرة حتى تتمكّن من التعرّف على واجهة برمجة التطبيقات وخياراتها:

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

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

جرِّبها الآن.

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

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

  2. يمكنك تعديل مَعلمات الطلب إذا أردت.

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

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