تخطّي إلى المحتوى

وثائق API

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

احصل على مفتاح API لتتبع استخدامك
الرابط الأساسيhttps://sunset-predictor.com
مواصفات OpenAPI

البداية السريعة

احصل على توقع غروب في ثوانٍ

curl -H "x-api-key: $SUNSET_API_KEY" \
  "https://sunset-predictor.com/api/v1/predict?city=Paris"

استبدل $SUNSET_API_KEY بمفتاح من لوحة التحكم. تعمل الطلبات غير المصادق عليها للعروض السريعة لكنها أكثر صرامة ولا تُعيد رؤوس rate-limit.

مثال على الاستجابة

{
  "score": 78,
  "label": "High",
  "explanation": "Scattered clouds and clean air should produce vivid colors near the horizon.",
  "confidence": "high",
  "location": "Paris, FR",
  "predictionType": "sunset",
  "sunsetTime": "2026-05-26T19:42:00Z",
  "sunriseTime": "2026-05-26T04:51:00Z",
  "timezone": "Europe/Paris",
  "targetDate": "2026-05-26",
  "rawFactors": {
    "cloudCover": 15,
    "humidity": 55,
    "visibility": 18200,
    "windSpeed": 5.2,
    "windDegree": 180,
    "rainProb": 0,
    "condition": "clouds",
    "temperature": 19.4,
    "dewPoint": 10.2,
    "pressure": 1015,
    "aqi": 2
  }
}

المصادقة

تُصادَق الطلبات الخارجية عبر ترويسة x-api-key. أنشئ مفتاحًا من لوحة التحكم الخاصة بك — يُعرض المفتاح الخام مرة واحدة فقط بالضبط.

الترويسة

x-api-key: sp_live_YOUR_API_KEY_HERE

أرسل مفتاح API الخاص بك في ترويسة الطلب x-api-key في كل استدعاء.

النطاقات

النطاقالوصف
predict:readقراءة توقعات الغروب (مطلوب لـ /api/predict)
usage:readقراءة إحصائيات استخدام هذا المفتاح نفسه (مطلوب لـ /api/usage)

الحدود

الفئة المجانية — 100 طلب يوميًا لكل مفتاح، تُعاد الحصة عند منتصف الليل بتوقيت UTC.

ترويسات استجابة حد المعدل

تحمل كل استجابة مصادَق عليها ناجحة هذه الترويسات حتى تتمكن من تتبع الحصة في الوقت الفعلي:

X-RateLimit-Limitالحد الأقصى للطلبات المسموح بها في النافذة الحالية
X-RateLimit-Remainingالطلبات المتبقية اليوم
X-RateLimit-Resetطابع زمني بصيغة ISO 8601 يحدد وقت إعادة ضبط الحصة
Retry-Afterعدد الثواني التي يجب الانتظارها قبل إعادة المحاولة (في حالة 429 فقط)

مثال على طلب مصادَق عليه

curl -H "x-api-key: sp_live_YOUR_API_KEY_HERE" \
  "https://sunset-predictor.com/api/v1/predict?city=Paris"

مرجع نقاط النهاية

ساحة تجربة API

اختبر API مباشرة من متصفحك

احصل على مفتاح ←

يبدأ بـ sp_live_ ويتكوّن من 40 حرفًا

مُخزَّن فقط في علامة تبويب المتصفح هذه (sessionStorage). يُمسح عند إغلاق علامة التبويب.

من اليوم حتى 5 أيام قادمة. اتركه فارغًا لليوم.

رابط الطلب

GET /api/v1/predict?city=Paris

أمثلة الكود

أمثلة جاهزة للاستخدام بلغات شائعة

# Set your API key once (mint from /dashboard/api-keys)
export SUNSET_API_KEY="sp_live_YOUR_API_KEY_HERE"

curl -H "x-api-key: $SUNSET_API_KEY" \
  "https://sunset-predictor.com/api/v1/predict?city=Paris"

تتحدث الأمثلة فوريًا مع معاملات الـ playground أعلاه.

استجابات الأخطاء

استجابات الأخطاء الشائعة ومعانيها

400خطأ في العميل

طلب غير صالح

معاملات مفقودة أو غير صالحة. قدم إما المدينة أو خط العرض/الطول.

{
  "error": "Either lat/lon or city must be provided"
}
401المصادقة / الصلاحيات

غير مصرّح

مفتاح API مفقود أو غير صحيح التنسيق أو مُلغى. أرسل مفتاحًا صالحًا في ترويسة x-api-key.

{
  "error": "Invalid or revoked API key",
  "code": "unauthorized"
}
403المصادقة / الصلاحيات

ممنوع

المفتاح صالح لكنه يفتقر إلى نطاق predict:read المطلوب لهذه النقطة الطرفية.

{
  "error": "Insufficient permissions. Required scope: predict:read",
  "code": "insufficientScope"
}
404خطأ في العميل

غير موجود

لم يتم العثور على المدينة المحددة.

{
  "error": "City not found",
  "code": "cityNotFound"
}
429خطأ في العميل

طلبات كثيرة جدًا

تم تجاوز الحصة اليومية (100 طلب/يوم في الفئة المجانية). تُعاد عند منتصف الليل بتوقيت UTC؛ تحقق من ترويسة Retry-After.

{
  "error": "Daily rate limit exceeded (100 requests/day). Upgrade your plan for higher limits.",
  "code": "rateLimitExceeded",
  "retryAfter": 3600
}
500خطأ في الخادم

خطأ في الخادم

حدث خطأ داخلي في الخادم. يرجى المحاولة لاحقاً.

{
  "error": "Internal server error"
}
502خطأ في الخادم

بوابة سيئة

فشل مزوّد الترميز الجغرافي الخارجي. أعد المحاولة بعد تأخير بسيط؛ ضع في اعتبارك إرسال lat/lon لتجاوز الترميز الجغرافي.

{
  "error": "Unable to look up city location",
  "code": "geocodingFailed"
}

أفضل الممارسات

تخزين الاستجابات مؤقتاً

يتم تخزين التوقعات مؤقتاً لمدة 30 دقيقة. تجنب الاستعلام بشكل أكثر تكراراً.

نطاق التاريخ

التوقعات متاحة من اليوم حتى 5 أيام قادمة. التواريخ الأبعد تعطي نتائج أقل دقة.

تفضيل الإحداثيات

استخدام خط العرض/الطول أكثر دقة ويتجنب الغموض مع أسماء المدن المشتركة عبر المناطق.

التعامل مع الأخطاء بلطف

تحقق دائماً من رمز حالة HTTP وتعامل مع استجابات 400/404/500 بشكل مناسب.

احترم حدود المعدل

اقرأ X-RateLimit-Remaining في كل استجابة. عند 429، انتظر نافذة Retry-After (إعادة الضبط عند منتصف الليل بتوقيت UTC) قبل إعادة المحاولة.

احتفظ بالمفاتيح على جانب الخادم

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

الاستخدام والترخيص

متى تكفي الخطة المجانية — ومتى تحتاج إلى خطة مدفوعة.

الخطة المجانية

مجانية للاستخدام الشخصي والهوايات والمنزل الذكي والاختبار.

  • •المشاريع الشخصية والنماذج الأولية
  • •الهواية والتعلّم
  • •لوحات المنزل الذكي (مثل Home Assistant) للاستخدام الشخصي
  • •الاختبار والتقييم

100 طلب يوميًا لكل مفتاح API.

خطة Plus

حدود شخصية أعلى وموقع بدون إعلانات. للاستخدام الشخصي فقط — المشاريع التجارية تحتاج إلى Pro.

200 طلب يوميًا لكل مفتاح API، 2 مفاتيح API.

الاستخدام التجاري

يتطلب الاستخدام التجاري خطة مدفوعة — Pro أو Business.

الخطط المدفوعة لها حدود يومية أعلى وتسمح بمزيد من مفاتيح API.

عرض الأسعار

يبقى Home Assistant وغيره من تكاملات المنزل الذكي مسموحًا في الخطة المجانية للاستخدام الشخصي غير التجاري.

احتفظ بمفتاح API سريًا. استخدمه من جانب الخادم ولا تضمّنه أبدًا في كود العميل العام أو ترفعه إلى مستودع.

تبني شيئاً تجارياً أو واجهت حدّاً لا يمكنك تجاوزه؟ تواصل مع الدعم