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

توفّر نقطة النهاية 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 شدة هطول الأمطار في الجزء (PrecipitationIntensity)، وتشمل القيم ما يلي:
  • PRECIPITATION_INTENSITY_UNSPECIFIED
  • NO_INTENSITY
  • MID_LIGHT
  • LIGHT
  • MID_MODERATE
  • MODERATE
  • MID_HEAVY
  • 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"
    },
    ...
  ]
}