الإجازة الرسمية التالية

ابحث عن إجازة رسمية واحدة في تاريخ مدني محلي محدد أو بعده.

طلب

متاح للسنوات والدول المنشورة باستخدام مفتاح Narwhal الخاص بك. تحقّق من التغطية والنطاق قبل طلب تاريخ.

GET /v1/calendars/holidays/{country}/next?from_date={from_date}

curl "https://api.narwhalapi.com/v1/calendars/holidays/IDN/next?from_date=2026-08-01" \
  -H "Authorization: Bearer $NARWHAL_API_KEY"

المعلمات

الاسم	النوع	قاعدة
`country`	سلسلة نصية	قيمة مطلوبة في المسار. رمز ISO أبجدي ثلاثي واحد مدعوم بأحرف كبيرة، مثل IDN.
`from_date`	سلسلة نصية تمثل تاريخًا	قيمة مطلوبة في الاستعلام، YYYY-MM-DD، بسنة من 1900 إلى 2200. لا يوجد افتراض تلقائي لتاريخ اليوم.
`scope`	سلسلة نصية	مرشح استعلام اختياري: national_public أو regional_public أو bank أو federal_government أو central_government أو collective_leave أو public_sector أو private_sector. احذفه لإرجاع جميع الفئات المنشورة. إذا لم تتوفر تغطية منشورة للنطاق في البلد والسنة المحددين، يُرجع 404 calendar_not_published؛ وتسرد coverage في الاستجابة ذلك النطاق فقط.

لا يوجد مرشح تقسيم فرعي أو ترقيم صفحات. وترفض كائنات إدخال MCP الحقول الإضافية.

استجابة توضيحية

{
  "country": "IDN",
  "coverage": [
    {
      "scope": "collective_leave",
      "subdivision_codes": []
    },
    {
      "scope": "national_public",
      "subdivision_codes": []
    }
  ],
  "holiday": {
    "date": "2026-08-17",
    "name": "Independence Day",
    "local_name": "Proklamasi Kemerdekaan",
    "subdivision_codes": [],
    "scope": "national_public"
  }
}

تاريخ البداية مشمول. يبحث في السنة الحالية، ثم في السنة التالية عند الحاجة فقط. إذا كانت سنة يلزم قراءتها غير منشورة، يُرجع 404 calendar_not_published؛ ويُرجع فشل القراءة 503. لا يبحث بعد سنة 2200؛ وإذا لم يبقَ حدث في هذه السنة القصوى يُرجع holiday: null. قد تُرجع عطلات إقليمية. عندما تشترك أحداث عدة في أقرب تاريخ، يُختار أول حدث في الترتيب الثابت؛ استخدم نقطة نهاية التاريخ للحصول عليها جميعًا.

حقول العطلات المشتركة. يُحدَّد صراحةً ما إذا كان كل حدث يسري على المستوى الوطني أو الإقليمي.

استدعاء MCP المطابق

أرسل طلبًا مصادقًا عليه باستخدام POST /mcp مع Accept: application/json, text/event-stream.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "calendars_get_next_holiday",
    "arguments": {
      "country": "IDN",
      "from_date": "2026-08-01"
    }
  }
}

تحتوي النتائج الناجحة على isError: false، والاستجابة نفسها في structuredContent، وبيانات JSON المحوّلة إلى نص في content[0].text. تحتوي أخطاء النطاق على isError: true.

الأخطاء والحصة

تعيد المدخلات غير الصالحة 400؛ وتعيد المفاتيح المفقودة أو غير الصالحة 401. وتعيد المسارات غير المسجّلة 404. ويعيد بلوغ حد معدل الطلبات أو استنفاد الحصة 429. ويعيد تقويم البلد والسنة غير المنشور 404 calendar_not_published؛ أما التقويم الذي يتعذر تقديمه بأمان حاليًا فيعيد 503 calendar_coverage_unavailable.

يُرجع 403 plan_upgrade_required عندما تكون السنة أو التاريخ أو النطاق قبل نافذة السجل في خطتك (Free لمدة 12 شهرًا، وBasic لمدة 5 سنوات، وPro للسجل الكامل).

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

جميع عمليات التقويم · التغطية والتفسير