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

استرجع التقويم المنشور الكامل لدولة وسنة واحدة.

طلب

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

GET /v1/calendars/holidays/{country}/{year}

curl "https://api.narwhalapi.com/v1/calendars/holidays/IDN/2026" \
  -H "Authorization: Bearer $NARWHAL_API_KEY"

المعلمات

الاسم	النوع	قاعدة
`country`	سلسلة نصية	قيمة مطلوبة في المسار. رمز ISO أبجدي ثلاثي واحد مدعوم بأحرف كبيرة، مثل IDN.
`year`	عدد صحيح	قيمة مسار مطلوبة بين 1900 و2200 شاملًا. ولا يضمن هذا النطاق توفر التغطية التاريخية.
`version_id`	سلسلة UUID	قيمة استعلام اختيارية من resource_version في حدث عطلة. تقرأ تقويم البلد والسنة غير القابل للتغيير ما دامت حقوق المصدر متاحة. احذفها لقراءة التقويم الحالي. يُرجع الإصدار غير المعروف 404 calendar_not_published؛ ويُرجع فشل القراءة 503.
`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": []
    }
  ],
  "holidays": [
    {
      "date": "2026-08-17",
      "name": "Independence Day",
      "local_name": "Proklamasi Kemerdekaan",
      "subdivision_codes": [],
      "scope": "national_public"
    }
  ]
}

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

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

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

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "calendars_list_holidays",
    "arguments": {
      "country": "IDN",
      "year": 2026
    }
  }
}

تحتوي النتائج الناجحة على 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 للسجل الكامل).

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

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