Method: history.lookup

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

طلب HTTP

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

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

نص الطلب

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

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

integer

اختياريّ. الحد الأقصى لعدد سجلّات المعلومات المعروضة كل ساعة المطلوب عرضها لكل صفحة القيمة التلقائية هي 72، والحد الأقصى للقيمة هو 168 (7 أيام من البيانات).
pageToken

string

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

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

object (LatLng)

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

enum (ExtraComputation)

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

enum (ColorPalette)

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

object (CustomLocalAqi)

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

string (Timestamp format)

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

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

طابع زمني بتنسيق RFC3339 UTC "Zulu" ، مع دقة نانوثانية وما يصل إلى تسعة أرقام كسرية. أمثلة: "2014-10-02T15:01:23Z" و " 2014-10-02T15:01:23.045123456Z".

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

integer

رقم من 1 إلى 720 يشير إلى نطاق ساعات الطلب. على سبيل المثال: إذا كانت القيمة 48، ستظهر البيانات من آخر 48 ساعة.
period

object (Interval)

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

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

boolean

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

string

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

نص الاستجابة

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

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

object (HourInfo)

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

string

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

string

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

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

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

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

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

HourInfo

يحتوي على معلومات عن جودة الهواء لكل ساعة في النطاق المطلوب. على سبيل المثال، إذا كان الطلب متعلقًا بالسجلّ لمدة 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)

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