البداية

ما هذا#

تقدّم Climate Memory ثلاثة منتجات من مضيفَين اثنين، بمفتاح API واحد.

مضيفان لا مضيف واحد لأن درجات-اليوم تقرأ أرشيفًا آخر بملمح تكلفة مختلف، وفصلهما يتيح أن يبطؤ أحدهما دون أن يُبطئ الآخر. ولا يعنيك من ذلك شيء سوى نسخ عنوان URL الأساسي الصحيح.

نداؤك الأول#

ثلاث خطوات، ومجملها نحو دقيقة.

1. احصل على مفتاح

أنشئ حسابًا على developers.climatememory.com/signin. الخطة المجانية لا تطلب بطاقة، وتمنحك 10 000 رصيد شهريًا، ويظهر مفتاحك على الشاشة فورًا. احتفظ به في متغير بيئة — فكل الأمثلة أدناه تقرأ $API_KEY.

export API_KEY="wd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

2. أجرِ النداء

curl -sH "X-API-Key: $API_KEY" \
  "https://api.climatememory.com/v1/forecast?lat=48.85&lon=2.35&days=3"

import os, httpx

r = httpx.get(
    "https://api.climatememory.com/v1/forecast",
    params={"lat": 48.85, "lon": 2.35, "days": 3},
    headers={"X-API-Key": os.environ["API_KEY"]},
    timeout=30,
)
r.raise_for_status()
data = r.json()
print(data["daily"]["temperature_2m_max"])

const res = await fetch(
  "https://api.climatememory.com/v1/forecast?lat=48.85&lon=2.35&days=3",
  { headers: { "X-API-Key": process.env.API_KEY } },
);
if (!res.ok) {
  const { error } = await res.json();
  throw new Error(`${error.code}: ${error.message}`);
}
const data = await res.json();
console.log(data.daily.temperature_2m_max);

req, _ := http.NewRequest("GET",
    "https://api.climatememory.com/v1/forecast?lat=48.85&lon=2.35&days=3", nil)
req.Header.Set("X-API-Key", os.Getenv("API_KEY"))

res, err := http.DefaultClient.Do(req)
if err != nil { return err }
defer res.Body.Close()

var out struct {
    Daily struct {
        TemperatureMax []float64 `json:"temperature_2m_max"`
    } `json:"daily"`
}
json.NewDecoder(res.Body).Decode(&out)

3. اقرأ الجواب

تعود كل السلاسل موجَّهة بالأعمدة — مصفوفات متوازية تتشارك فهرس time واحدًا، لا قائمة كائنات. انظر أعراف الاستجابة لمعرفة السبب وطريقة القراءة.

الاستيثاق#

أرسل مفتاحك في ترويسة X-API-Key مع كل طلب. لا يوجد مسار OAuth، ولا رمز bearer يحتاج تجديدًا، ولا توقيع يُحسب.

X-API-Key: wd_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

تُخزَّن المفاتيح مُجزَّأة. وإذا فقدت مفتاحًا فإنه يُدوَّر لا يُستعاد — لا يمكننا أن نعرضه عليك ثانية لأننا لا نملكه أصلًا. والتدوير متاح في وحدة التحكم ويصدر مفتاحًا جديدًا فورًا.

الـ scopes

يحمل المفتاح scopes، والخطة هي التي تقرر أيّها. ونداء نقطة نهاية خارج scopes مفتاحك يعيد 403 scope_denied — وهذه مشكلة خطة لا مشكلة مفتاح، والرسالة تقول ذلك.

أما نقاط نهاية الترميز الجغرافي فلا تتطلب أيًّا منها. فأي مفتاح صالح يحلّ اسم مكان، في أي خطة، لأن كل منتج هنا يحتاج إحداثية قبل أن يجيب عن أي شيء. انظر الترميز الجغرافي.

الترميز الجغرافي#

المعاملات

الكتالوج هو صنف المعالم P من GeoNames بأكمله — كل مكان مأهول على الأرض، حتى القرى الصغيرة التي لا يتجاوز سكانها بضع عشرات، لا مستخرَجًا مُرشَّحًا بعدد السكان. قرية فيها 528 نسمة موجودة فيه.

المطابقة لا تُقيَّد باللغة أبدًا

يُختبر الاستعلام مقابل الاسم المحلي ونقحرته اللاتينية وكل الأسماء البديلة المترجمة، مهما كانت قيمة lang. وهذا أهم مما يبدو: 98 % من الأماكن ليس لها اسم مترجم أصلًا — والفرنسية تغطي 1.84 % من الكتالوج — فالبحث المرشَّح باللغة يجد العواصم ولا شيء غيرها. lang يختار أي اسم يعود ويؤثر في الترتيب؛ لكنه لا يقرر أبدًا ما هو مؤهل للظهور.

GET /v1/geocode?q=ramillies&lang=fr
GET /v1/geocode?q=ramillies&lang=fr&near=50.63,3.06   # من ليل
GET /v1/geocode?q=bruxelles&lang=fr                     # اسم أجنبي، عبر فهرس الأسماء البديلة
GET /v1/geocode?q=zuesch&lang=de                        # الأوملاوت مكتوبًا مبسوطًا

كيف تُرتَّب النتائج

تحمل كل نتيجة score، وتحمل distance_km إذا أُعطي near. ويجمع الترتيب أربع إشارات: جودة تطابق الاسم، وأهمية المكان، وقربه من near، وما إذا كان الاسم المطابق باللغة المطلوبة.

لماذا يوجد near. هناك راميّي (Ramillies) اثنتان — واحدة فيها 5 749 نسمة في برابانت الوالونية، وأخرى فيها 528 في منطقة أعالي فرنسا، وبينهما 126 كم. ولا واحدة منهما هي الجواب الصحيح في المطلق. فبلا near تعود الأكبر؛ ومن مدينة ليل تعود الفرنسية.

الأهمية ليست عدد السكان وحده. 90.7 % من الكتالوج بلا عدد سكان مسجَّل — فـ GeoNames لا ينشر أي عدد لبعض البلدان — ولذلك يتولى نوع المكان (عاصمة وطنية، مقر وحدة إدارية، مكان عادي، حي) حمل الترتيب حيثما غاب عدد السكان.

الأوملاوت يُبسط ولا يُحذف. لوحة مفاتيح ألمانية أو دنماركية بلا علامات تشكيل تكتب Zuesch بدل Züsch وKoeln بدل Köln. وGeoNames لا يحمل هذا الرسم — فصيغته اللاتينية Zusch، بحذف الأوملاوت لا ببسطه — ولذلك يُولَّد هنا. والرسمان كلاهما يصلان إلى المكان، والنتيجة تعرض الاسم الحقيقي في الحالتين.

البحث عن المدن#

/v1/cities/search أقدم من /v1/geocode ويحافظ على عقده لمن بنوا عليه من قبل: فهو يطابق الاسم اللاتيني فقط ويرتب حسب عدد السكان.

/v1/cities/nearest هو الاتجاه المعاكس، وهو ما يحوّل تحديد موقع GPS إلى slug مدينة يمكنك تمريره بعدها إلى نقاط نهاية المدن. ويأخذ lat وlon وmax_km اختياريًا.

وكلاهما يُحسب على سقف الترميز الجغرافي نفسه الخاص بـ /v1/geocode، ولا يكلّف أي منهما أرصدة.

أعراف الاستجابة#

ست قواعد تسري على كل نقاط النهاية. تعلّمها مرة واحدة، وما بقي من هذه الوثائق مجرد أسماء حقول.

1. السلاسل أعمدة لا صفوف

كل سلسلة زمنية مجموعة مصفوفات متوازية تتشارك فهرس time واحدًا، بدل مصفوفة كائنات:

"hourly": {
  "time":           ["2026-08-01T00:00:00+00:00", "2026-08-01T01:00:00+00:00"],
  "temperature_2m": [18.4, 18.1],
  "precipitation":  [0.0, 0.2]
}

الفهرس i في كل مصفوفة يصف اللحظة نفسها. وهذا أصغر على الشبكة من صيغة الصفوف بثلاث إلى خمس مرات، ويُفكَّك مباشرة إلى إطار بيانات أو مكتبة رسم بلا تحويل، وهو ما تتوقعه أصلًا العملاء المكتوبة على نسق Open-Meteo. ولتصفحها كصفوف:

rows = zip(h["time"], h["temperature_2m"], h["precipitation"])

2. الأوقات بصيغة ISO 8601 بإزاحة صريحة

دائمًا. 2026-08-01T00:00:00+00:00، لا سلسلة محلية مجردة ولا عدد Unix صحيح. وحين تمرر timezone تكون الإزاحة في الاستجابة إزاحة تلك المنطقة — فتصير السلسلة وحدها قاطعة، ولا تحتاج أبدًا إلى معرفة ما افترضناه نحن.

3. الوحدات وحدات النظام الدولي، ثابتة ولا تُتفاوض

°م، ملم، م/ث، هكتوباسكال، و/م²، أمتار. ولا يوجد معامل units=imperial عن قصد: مفتاح تبديل الوحدات حقل يتوقف معناه على حقل آخر، وهكذا ينتهي المُنادي إلى رسم فهرنهايت على محور مئوي بعد تغيير إعدادات لم يراجعه أحد. حوِّل عند حافتك أنت، حيث يوجد القارئ.

ونقاط النهاية ذات الوحدات غير المألوفة ترسل في الاستجابة كتلة units تسميها صراحة، بدل أن تراهن على ذاكرتك.

4. null تعني «غير معروف» لا «صفر» أبدًا

الساعة الغائبة تكون null في المصفوفة، محتفظة بموضعها كي تبقى الفهارس متحاذية. ولا تُملأ صامتة بصفر أبدًا — فبالنسبة للهطول هما ادعاءان متضادان، وأحدهما كذبة عن جفاف.

5. كل استجابة تقول من أين جاءت

ترافق البياناتِ كتلةُ source (الطقس) أو كتلة quality (الأرشيفات): أي نموذج أو تشغيل أجاب، وكم عمره، وكم كانت الفترة مكتملة. فلا تحتاج أبدًا إلى استنتاج الطزاجة من الساعة.

6. القديم خير من لا شيء

إذا كان أحدث تشغيل لنموذجنا أقدم من المتوقع، فإننا نجيب رغم ذلك — مع "stale": true وdata_age_hours في كتلة source — بدل إعادة 503. فتنبؤ عمره ثماني ساعات أنفع من خطأ. تحقق من العلامة إن كانت الطزاجة حاسمة عندك؛ وتجاهلها إن لم تكن.

حدود المعدل والأرصدة والحصة#

تسري ثلاثة حدود مستقلة، وتفشل كلٌّ منها على نحو مختلف عن قصد. وكل استجابة ناجحة تخبرك أين تقف:

أرصدة لا طلبات

تنبؤ مدينة من الذاكرة المؤقتة قراءة تستغرق 3 ملّي ثانية. أما عشر سنوات من درجات-اليوم الساعية لخمسمئة موقع فلا. والتسعير بالطلب كان سيسمح لمُنادٍ أن يبقى داخل حصته وأن يكلّف أكثر مما يدفع، وبوجه مشروع تمامًا — ولذلك تتوقف تكلفة النداء على مقدار الأرشيف الذي يحرّكه.

ماذا تفعل عند بلوغ كل حد

تمتد فترة حصتك من تاريخ اشتراكك إلى اليوم نفسه من الشهر التالي — وهي الفترة التي تفوترها Stripe — ويبدأ العدّاد كاملًا من جديد في كل مرة. وترويسة X-Quota-Resets-At تحمل ذلك التاريخ في كل استجابة، فاقرأها بدل افتراض أول الشهر. أما الحسابات بلا اشتراك فتتبع الشهر الميلادي.

الأخطاء#

كل خطأ له الشكل نفسه، على المضيفَين كليهما:

{
  "error": {
    "code": "range_too_long",
    "message": "Requested span is 14.0 years; the maximum per request is 10.",
    "max_years": 10
  }
}

هذه هي القائمة كلها، وتُقارَن بالشيفرة المصدرية في كل بناء: فرمز منشور هنا لا يرفعه أي معالج يُسقط مجموعة الاختبارات، وكذلك معالج يرفع رمزًا لا يحمله هذا الجدول. وإن صادفت رمزًا ليس أعلاه فذلك عيب في هذه الصفحة لا قيمة ينبغي أن تعالجها معالجة خاصة.

سياسة إعادة محاولة ناجحة

RETRY = {"rate_limited", "data_unavailable"}

def should_retry(status, code, attempt):
    if code == "quota_exceeded":
        return False              # لا شيء يتغير قبل إعادة التعيين
    if code == "geocode_quota_exceeded":
        return False              # ولا تتوقف: الأرصدة ما زالت تعمل
    if code in RETRY:
        return attempt < 5
    return status >= 500

الدقة — ما الذي تتوقعه#

نفضّل ضبط التوقعات ضبطًا صحيحًا على أن تكتشف الحدود في بيئة الإنتاج.

حيث يكون التنبؤ قويًا

الحرارة والضغط والرياح السينوبتية والرطوبة وسطوع الشمس. ويبلغ الخطأ المعتاد لحرارة الـ 2 م عند 24 ساعة نحو 1–1.5 °م. وECMWF أفضل نموذج حتمي عالمي في العالم، وهو ما تحصل عليه.

حيث يضعف

العواصف الحملية — فخلية عرضها 28 كم لا تحلّ عاصفة رعدية، وحتى 3 كم لا تعدو التلميح إليها. وكذلك الموضع والتوقيت الدقيقان للزخات. والمناخ الصغري الساحلي والجبلي دون استبانة النموذج. ونسيم البحر وبرك الهواء البارد في الوديان، وهي ما لا يُنمذجه تصحيح التضاريس.

أمانة جغرافية

في فرنسا وألمانيا والولايات المتحدة وكندا نقدّم نماذج وطنية باستبانة 1.3–3 كم، وقرية صغيرة تحصل فعلًا على خلية شبكة خاصة بها. وفي بقية أوروبا تحصل على 6.5 كم. وعبر إفريقيا والشرق الأوسط ومعظم آسيا يكون أفضل نموذج عام متاح بين 13 و28 كم، فتحصل على طقس المنطقة لا طقس الشارع. وتصحيح التضاريس يضيّق تلك الفجوة لكنه لا يغلقها.

درجات-اليوم

إعادة التحليل الشبكية تغطي كل مكان، بما في ذلك مواقع لا محطة أرصاد فيها ضمن 60 كم — وتلك ميزتها على المزودين المعتمدين على المحطات. وضعفها مراكز المدن التي تقرؤها إعادة التحليل أقل من حقيقتها؛ ونقاط نهاية المدن تطبّق تصحيحًا معايَرًا، أما نقاط نهاية الإحداثيات فلا.

حقلان تقديريان، ونفضّل قول ذلك

uv_index مشتق من ارتفاع الشمس والإشعاع عريض النطاق، لا من عمود الأوزون — بدقة نحو ±1 وحدة. وprecipitation_probability_proxy تقدير لا احتمال؛ والاحتمال الحقيقي في /v1/probability. وكلاهما مشروح بالكامل في مرجع الحقول.

الخطط#

الترميز الجغرافي خارج هذا الجدول: فهو لا يكلّف أرصدة في أي خطة، وله سقفه الخاص وهو خمسة طلبات لكل رصيد. انظر حدود المعدل والحصة.

الفوترة السنوية تعني شهرين مجانًا. والكتالوج الحي على developers.climatememory.com/pricing — وتلك الصفحة تقرأ نظام الفوترة مباشرة، فإن اختلفا يومًا فهي المرجَّحة.

ولا توجد نقطة نهاية للتصدير الجملي في أي خطة. أما تصدير CSV فموجود على أرشيفي درجات-اليوم والمناخ، ومقيَّد بالمجال نفسه الذي يقيَّد به نداء JSON المكافئ، ولا يعيد إلا صفوفًا مجمَّعة — لا السلسلة الساعية أبدًا.

النسبة والترخيص#

ونقطتا النهاية أعلاه لا تحتاجان مفتاحًا، فيمكنك توليد التنويه من الواجهة بدل تثبيت نص في الشيفرة يتقادم حين يتغير مصدر. كما تسافر نسبة التشغيل المحدد الذي أجاب مع كل استجابة بيانات، في source.attribution وفي ترويسة X-Data-Attribution.

لك أن تذكر أنك تستعمل هذه البيانات. وليس لك أن توحي بأن أيًّا من هذه المنظمات أنتجت منتجك أو أقرّته أو تدعمه.

إخلاء مسؤولية

تُقدَّم التنبؤات دون ضمان. ولا تتحمل المفوضية الأوروبية ولا ECMWF ولا DWD ولا NOAA ولا Météo-France أي مسؤولية عن أي استعمال لهذه المعلومات. ولا تستعملها أساسًا وحيدًا لقرارات تكون فيها الحياة أو السلامة أو الممتلكات في خطر.

وثمة قيد واحد ليس لنا أن نتنازل عنه: رخصة Copernicus تحصر تحذيرات الفيضان بالسلطات الوطنية والإقليمية. انظر الأنهار.