Method: forecast.lookup

لعرض توقّعات جودة الهواء في موقع جغرافي معيّن خلال نطاق زمني محدّد

طلب HTTP

POST https://airquality.googleapis.com/v1/forecast:lookup

يستخدم عنوان URL بنية تحويل الترميز gRPC.

نص الطلب

يحتوي نص الطلب على بيانات بالبنية التالية:

تمثيل JSON 
{
  "location": {
    object (LatLng)
  },
  "extraComputations": [
    enum (ExtraComputation)
  ],
  "uaqiColorPalette": enum (ColorPalette),
  "customLocalAqis": [
    {
      object (CustomLocalAqi)
    }
  ],
  "pageSize": integer,
  "pageToken": string,
  "dateTime": string,
  "period": {
    object (Interval)
  }
  // End of list of possible types for union field time_range.
  "universalAqi": boolean,
  "languageCode": string
}
الحقول
location

object (LatLng)

مطلوبة. تمثّل هذه السمة خط العرض وخط الطول الذي تبحث عنه واجهة برمجة التطبيقات عن بيانات جودة الهواء.
extraComputations[]

enum (ExtraComputation)

اختياريّ. ميزات إضافية يمكن تفعيلها بشكل اختياري. سيؤدي تحديد عمليات حسابية إضافية إلى عرض العناصر والحقول ذات الصلة في الاستجابة.
uaqiColorPalette

enum (ColorPalette)

اختياريّ. لتحديد لوحة الألوان المستخدَمة للبيانات المقدَّمة من "مؤشر جودة الهواء العالمي" (UAQI). لوحة الألوان هذه مناسبة لـ UAQI فقط، بينما تحتوي مؤشرات جودة الهواء الأخرى على لوحة ألوان محددة مسبقًا لا يمكن التحكم فيها.
customLocalAqis[]

object (CustomLocalAqi)

اختياريّ. للتعبير عن علاقة "البلد/المنطقة بمؤشر جودة الهواء". يعمل هذا الخيار على إقران بلد أو منطقة بمؤشر جودة الهواء المطلوب ليتم عرض بيانات جودة الهواء المطلوبة لهذا البلد أو المنطقة وفقًا لمؤشر جودة الهواء الذي تم اختياره. يمكن استخدام هذه المَعلمة لتحديد مؤشر جودة الهواء غير تلقائي لبلد معيّن، مثلاً للحصول على مؤشر وكالة حماية البيئة (EPA) في الولايات المتحدة لكندا بدلاً من المؤشر التلقائي لكندا.
pageSize

integer

اختياريّ. الحد الأقصى لعدد سجلات المعلومات التي يمكن عرضها في كل ساعة (العدد التلقائي = 24).
pageToken

string

اختياريّ. رمز مميّز للصفحة تم تلقّيه من استدعاء سابق للتوقعات. ويتم استخدامه لاسترداد الصفحة التالية.
dateTime

string (Timestamp format)

طابع زمني يتم عرض البيانات له عند نقطة زمنية محدّدة. ويتم تقريب الطابع الزمني إلى الساعة السابقة بالضبط.

سيؤدي ذلك إلى عرض بيانات كل ساعة للطابع الزمني المطلوب فقط (أي عنصر معلومات واحد كل ساعة). على سبيل المثال، سيتم تقريب الطلب الذي تم إرساله حيث تم ضبط المَعلمة dateTime على 2023-01-03T11:05:49Z إلى 2023-01-03T11:00:00Z.

ملاحظة: يمكن استخدام dateTime أو startTime وendTime في طلب.
period

object (Interval)

يشير إلى الفترة startTime وendTime التي يمكن الحصول على بيانات التوقّعات خلالها. تشمل السمة endTime الخدمات الشاملة. ويتم تقريب الطابع الزمني إلى الساعة السابقة بالضبط.

ملاحظة: يمكن استخدام dateTime أو startTime وendTime في طلب.
universalAqi

boolean

اختياريّ. وفي حال ضبطها على "صحيح"، سيتم تضمين مؤشر جودة الهواء العام في حقل "الفهارس" بالاستجابة (القيمة التلقائية = صحيح).
languageCode

string

اختياريّ. السماح للعميل باختيار لغة الردّ إذا تعذّر توفير بيانات لتلك اللغة، ستستخدم واجهة برمجة التطبيقات أقرب تطابق. تعتمد القيم المسموح بها على معيار مجموعة مهندسي شبكة الإنترنت (IETF) (القيمة التلقائية = 'en').

نص الاستجابة

عنصر الاستجابة لواجهة برمجة التطبيقات الخاصة بتوقعات جودة الهواء

إذا كانت الاستجابة ناجحة، سيحتوي نص الاستجابة على بيانات بالبنية التالية:

تمثيل JSON 
{
  "hourlyForecasts": [
    {
      object (HourlyForecast)
    }
  ],
  "regionCode": string,
  "nextPageToken": string
}
الحقول
hourlyForecasts[]

object (HourlyForecast)

اختياريّ. يحتوي على معلومات عن جودة الهواء لكل ساعة في النطاق المطلوب. على سبيل المثال، إذا كان الطلب يهدف إلى 48 ساعة من التوقّعات، سيكون هناك 48 عنصرًا من التوقّعات لكل ساعة.
regionCode

string

اختياريّ. تمثّل هذه السمة رمز ISO_3166-1 alpha-2 للبلد أو المنطقة المتوافق مع الموقع الجغرافي المقدَّم في الطلب. قد يتم حذف هذا الحقل من الرد إذا كان الموقع الجغرافي المقدَّم في الطلب يقع في منطقة متنازع عليها.
nextPageToken

string

اختياريّ. الرمز المميز لاسترداد الصفحة التالية.

نطاقات التفويض

يجب توفير نطاق OAuth التالي:

  • https://www.googleapis.com/auth/cloud-platform

لمزيد من المعلومات، راجِع نظرة عامة على بروتوكول OAuth 2.0.

HourlyForecast

يحتوي على معلومات عن جودة الهواء لكل ساعة في النطاق المطلوب. على سبيل المثال، إذا كان الطلب يهدف إلى 48 ساعة من التوقّعات، سيكون هناك 48 عنصرًا من التوقّعات لكل ساعة.

تمثيل JSON 
{
  "dateTime": string,
  "indexes": [
    {
      object (AirQualityIndex)
    }
  ],
  "pollutants": [
    {
      object (Pollutant)
    }
  ],
  "healthRecommendations": {
    object (HealthRecommendations)
  }
}
الحقول
dateTime

string (Timestamp format)

طابع زمني مقرَّب يشير إلى الوقت (الساعة) الذي تشير إليه البيانات بالتنسيق RFC3339 UTC "Zulu". على سبيل المثال: "2014-10-02T15:00:00Z".
indexes[]

object (AirQualityIndex)

استنادًا إلى معلَمات الطلب، ستشمل هذه القائمة (ما يصل إلى) مؤشرَين لجودة الهواء:

  • مؤشر جودة الهواء العالمي سيتم عرضها إذا تم ضبط القيمة المنطقية universalAqi على "صحيح".
  • مؤشر جودة الهواء المحلي سيتم إرجاعه في حالة تحديد العملية الحسابية الإضافية LOCAL_AQI.
pollutants[]

object (Pollutant)

قائمة بالملوّثات التي تؤثر في الموقع الجغرافي المحدَّد في الطلب

ملاحظة: سيتم عرض هذا الحقل فقط للطلبات التي أدت إلى تحديد عملية واحدة أو أكثر من العمليات الحسابية الإضافية التالية: POLLUTANT_ADDITIONAL_INFO وDOINANT_POLLUTANT_CONCENTRATION وPOLLUTANT_CONCENTRATION.
healthRecommendations

object (HealthRecommendations)

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