API

ابحث عن المدينة أولاً ثم اطلب الحزمة الكاملة للوقت.

تتيح لك API الخاصة بـ SunriseTime اكتشاف slugs المدن أولاً ثم طلب بيانات الشمس والقمر والصلاة في استجابة واحدة منظمة. الفهرس الحالي يغطي 500 مدينة مفهرسة.

نموذج الوصول

نسخة عامة تجريبية
لا تتطلب مفتاح API حالياً
مناسبة للقراءة فقط وللأدوات الخفيفة
الهدف الحالي: 100 طلب لكل IP يومياً

أساسيات المنتج

مُصدّرة تحت /api/v1/
كل استجابة تحتوي على كتلة meta
دعم CORS للمتصفحات الخارجية ما زال محدوداً
استجابات JSON ترسل X-Robots-Tag: noindex

سياسة التخزين المؤقت

/api/v1/times: نافذة 15 دقيقة
/api/v1/cities: نافذة 60 دقيقة
/api/v1/openapi.json: نافذة 60 دقيقة

بداية سريعة

احصل على slug المدينة أولاً ثم اطلب أوقات تلك المدينة باستخدامه.

1. الحصول على slug المدينة

curl "https://sunrisetime.co/api/v1/cities?query=dubai&limit=3"

2. جلب بيانات الوقت

curl "https://sunrisetime.co/api/v1/times?city=dubai&date=2026-03-29"

المسارات

هذه المسارات الثلاثة تكفي لمعظم التكاملات الخارجية.

GET /api/v1/cities ابحث عن المدن بالاسم أو slug أو الدولة أو المنطقة ثم احصل على slugs ثابتة. GET /api/v1/times اجلب بيانات الشروق والغروب والساعة الذهبية والقمر ومواقيت الصلاة لمدينة وتاريخ واحد. GET /api/v1/openapi.json اقرأ وثيقة OpenAPI لعمل العملاء المولدين أو الأدوات الداخلية.

المعاملات

الأفضل إبقاء التدفق بسيطاً: slug أولاً ثم مدينة واحدة لكل طلب.

`/api/v1/cities`

المعامل	مطلوب	ملاحظات
`query`	لا	مدينة أو slug أو دولة أو منطقة إدارية. القيمة الفارغة تعيد مدناً شائعة.
`limit`	لا	الافتراضي 10 والحد الأقصى 25.

`/api/v1/times`

المعامل	مطلوب	ملاحظات
`city`	نعم	slug ثابت مثل dubai أو istanbul أو london.
`date`	لا	تاريخ محلي اختياري بصيغة YYYY-MM-DD.

شكل الاستجابة

تم تنظيم JSON حسب حالات الاستخدام لتسهيل الدمج.

JSON

meta: الإصدار، المسار، رابط الوثائق، مدة التخزين المؤقت، ونسخة من الاستعلام
city: slug، الاسم، الإحداثيات، المنطقة الزمنية وبيانات السكان
links: روابط الموقع وواجهة البرمجة المرتبطة بالمدينة
كتل sun و goldenHour و moon و prayerTimes

Sample response

{
  "meta": {
    "version": "v1",
    "endpoint": "/api/v1/times",
    "cacheTtlSeconds": 900
  },
  "city": {
    "slug": "dubai",
    "name": "Dubai",
    "timezone": "Asia/Dubai"
  },
  "sun": {
    "sunrise": "6:15 AM",
    "sunset": "6:33 PM"
  },
  "moon": {
    "phase": "Waxing Crescent",
    "illumination": 12
  },
  "prayerTimes": {
    "fajr": "5:00 AM",
    "maghrib": "6:34 PM"
  }
}

أمثلة تكامل

الاستخدام من الطرفية أو الخادم هو الأفضل حالياً. وصول المتصفحات الخارجية يجب أن ينتظر توسيع CORS.

cURL

curl "https://sunrisetime.co/api/v1/times?city=dubai&date=2026-03-29"

JavaScript

const cityLookup = await fetch("https://sunrisetime.co/api/v1/cities?query=dubai&limit=1");
const cityResult = await cityLookup.json();
const citySlug = cityResult.cities[0]?.slug;

const timingResponse = await fetch(`https://sunrisetime.co/api/v1/times?city=${citySlug}&date=2026-03-29`
);
const timingData = await timingResponse.json();

console.log(timingData.sun.sunrise, timingData.prayerTimes.maghrib);

نموذج الأخطاء

الأخطاء تعود بصيغة JSON منظمة لتسهيل التعامل معها خارجياً.

الرمز	الحالة	المعنى
`missing_city`	400	لم يتم إرسال city إلى /api/v1/times.
`invalid_date`	400	قيمة date ليست بصيغة YYYY-MM-DD.
`unknown_city`	404	slug المدينة المرسل غير موجود في الفهرس الحالي.
`invalid_limit`	400	قيمة limit المرسلة إلى /api/v1/cities غير صالحة.

خطوات تشغيلية تالية

استخدم هذه الروابط إذا أردت مراجعة المنهجية أو فحص slugs العامة أو طلب استخدام أعلى.

المنهجية راجع افتراضات الشمس والقمر والصلاة التي تقف خلف الاستجابة. فهرس المدن تصفح دليل المدن العام إذا أردت فحص slugs يدوياً. التواصل هل تحتاج إلى حجم أعلى أو مسار تكامل خاص؟ راسل hello@sunrisetime.co.