الحصول على توقعات الطقس كل دقيقة (تجريبية)

توفّر نقطة نهاية forecast:minutes توقعات عالية الدقة للهطول على أساس دقيقة بدقيقة (تُعرف أيضًا باسم التوقعات الآنية) لموقع جغرافي معيّن.

تعرض واجهة برمجة التطبيقات المعلومات التالية لفترة زمنية مدتها 6 ساعات:

  • وقت بدء وانتهاء الفترة الزمنية للتوقعات
  • المنطقة الزمنية للموقع الجغرافي المطلوب
  • وقت بدء وانتهاء كل شريحة من شرائح التوقعات
  • النوع المتوقّع للهطول واحتماليته وكميته وكثافته خلال كل شريحة

البنود

تم إصدار هذه البنود بموجب القسم 6 (بنود عروض مرحلة ما قبل التوفّر للجمهور العام) من بنود الخدمة المحدّدة في "منصة خرائط Google"، كما وافقت عليها أنت وGoogle.

1.1 متطلبات تحديد المصدر: على العميل تحديد المصدر لشركة Google وفقًا لـالمستندات إذا كان يستخدم محتوى "خرائط Google" من Weather API.

1.2 القيود: لا يمكن للعملاء استخدام محتوى "خرائط Google" الذي يتم استرداده من Weather API لإعادة إنشاء خدمة أو منتج من Google (على سبيل المثال، استخدام البيانات التي يتم استردادها من Weather API في تطبيق أو نموذج للطقس يكون هدفه الأساسي توفير معلومات عن الطقس).

1.3 التخزين المؤقت: يمكن للعملاء تخزين محتوى "خرائط Google" الساري مؤقتًا من Weather API لفترة التخزين المؤقت السارية، كما هو موضّح في الجدول 1.3.1 (أذونات التخزين المؤقت).

الجدول 1.3.1 (أذونات التخزين المؤقت)

تُضاف هذه الأذونات إلى الأذونات الموضّحة في الجدول 17.2.1 من بنود الخدمة المحدّدة في "منصة خرائط Google".

محتوى "خرائط Google" فترة التخزين المؤقت
قيم التوقعات الدقيقة ساعة واحدة، وبعدها على العميل حذف محتوى "خرائط Google" المخزّن مؤقتًا

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

لطلب توقعات دقيقة، أرسِل طلب استرداد بيانات باستخدام GET إلى:

https://weather.googleapis.com/v1/forecast/minutes:lookup?key=API_KEY&location.latitude=LATITUDE&location.longitude=LONGITUDE

أدرِج إحداثيات خط العرض وخط الطول للموقع الجغرافي في مَعلمات الطلب.

مَعلمات الطلب

تقبل نقطة نهاية forecast.minutes مَعلمات الطلب التالية:

المَعلمة الوصف مطلوبة أم اختيارية
location.latitude إحداثيات خط العرض للموقع الجغرافي المطلوب مطلوب
location.longitude إحداثيات خط الطول للموقع الجغرافي المطلوب مطلوب
unitsSystem نظام الوحدات المطلوب تشمل القيم ما يلي:
  • UNITS_SYSTEM_UNSPECIFIED
  • IMPERIAL
  • METRIC

إذا لم يتم تحديد نظام وحدات، سيتم تلقائيًا استخدام METRIC في الردّ.

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

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

تعرض Weather API الحقول التالية في نص الردّ:

الحقل الوصف
overallPredictionTimeframe الفترة الزمنية الإجمالية للتوقعات
overallPredictionTimeframe.startTime وقت بدء الفترة الزمنية للتوقعات يمثّل هذا الوقت نقطة المرجع الأولية.
overallPredictionTimeframe.endTime وقت انتهاء الفترة الزمنية للتوقعات يتم ضبط هذا الوقت بعد ست ساعات من وقت البدء.
timeZone المنطقة الزمنية للموقع الجغرافي المطلوب
segments شرائح التوقعات على مستوى الدقيقة، ويتم تمييزها من خلال timeFrame
segments.timeFrame الفترة الزمنية ذات الصلة بالشريحة
segments.timeFrame.startTime وقت بدء الشريحة
segments.timeFrame.endTime وقت انتهاء الشريحة
segments.type النوع المتوقّع للهطول خلال تلك الشريحة تشمل القيم ما يلي:
  • DOMINANT_PRECIPITATION_TYPE_UNSPECIFIED
  • NONE
  • RAIN
  • SNOW
  • HAIL
segments.probability الاحتمالية المتوقّعة للهطول خلال تلك الشريحة تكون القيم على شكل نسب مئوية تتراوح بين 0 و100.
segments.qpf التوقعات الكمية للهطول
segments.qpf.quantity الكمية المتوقّعة للهطول خلال تلك الشريحة
segments.qpf.unit الوحدة المستخدَمة لقياس كمية الهطول المتراكم (على سبيل المثال، MILLIMETERS أو INCHES)
segments.snowfallAmount الكمية المتوقّعة للثلوج خلال تلك الشريحة
segments.snowfallAmount.quantity الكمية المتوقّعة للثلوج (كمكافئ للمياه السائلة) خلال تلك الشريحة
segments.snowfallAmount.unit الوحدة المستخدَمة لقياس كمية الثلوج المتراكمة (على سبيل المثال، MILLIMETERS أو INCHES)
segments.intensity كثافة الهطول في قطاع الطريق تشمل القيم ما يلي:
  • PRECIPITATION_INTENSITY_UNSPECIFIED
  • NO_INTENSITY
  • LIGHT
  • MODERATE
  • HEAVY
nextPageToken رمز يمكن إرساله كـ pageToken لاسترداد الصفحة التالية إذا تم حذف هذا الحقل، يعني ذلك أنّه لا توجد صفحات لاحقة.

مثال على التوقعات الدقيقة

يطلب المثال التالي معلومات عن التوقعات الدقيقة لموقع جغرافي في ولاية فرجينيا الغربية:

curl -H "Content-Type: application/json" -X GET "https://weather.googleapis.com/v1/forecast/minutes:lookup?key=API_KEY&location.latitude=37.60451&location.longitude=-80.59044&unitsSystem=METRIC&pageSize=5"

في الردّ، يشير العنصر segments إلى كل شريحة من شرائح الفترة الزمنية الإجمالية للتوقعات:

  {
  "overallPredictionTimeframe": {
    "startTime": "2026-05-11T12:10:00Z",
    "endTime": "2026-05-11T18:12:00Z"
  },
  "timeZone": {
    "id": "America/New_York"
  },
  "segments": [
    {
      "timeFrame": {
        "startTime": "2026-05-11T12:20:00Z",
        "endTime": "2026-05-11T12:22:00Z"
      },
      "type": "RAIN",
      "probability": 21,
      "qpf": {
        "quantity": 0.1333,
        "unit": "MILLIMETERS"
      },
      "snowfallAmount": {
        "quantity": 0.0,
        "unit": "MILLIMETERS"
      },
      "intensity": "MODERATE"
    },
    {
      "timeFrame": {
        "startTime": "2026-05-11T12:22:00Z",
        "endTime": "2026-05-11T12:24:00Z"
      },
      "type": "RAIN",
      "probability": 21,
      "qpf": {
        "quantity": 0.1333,
        "unit": "MILLIMETERS"
      },
      "snowfallAmount": {
        "quantity": 0.0,
        "unit": "MILLIMETERS"
      },
      "intensity": "MODERATE"
    },
    ...
  ]
}