اعرض العطلات الرسمية

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

طلب

متاح للسنوات والدول المنشورة باستخدام مفتاح 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 شاملًا. ولا يضمن هذا النطاق توفر التغطية التاريخية.
`scope`	سلسلة نصية	مرشح استعلام اختياري: national_public أو regional_public أو bank أو federal_government أو central_government أو collective_leave أو public_sector أو private_sector. احذفه لإعادة جميع الفئات المنشورة.

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

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

{
  "country": "IDN",
  "year": 2026,
  "coverage": [
    {
      "scope": "national_public",
      "nationwide": true,
      "subdivision_codes": []
    },
    {
      "scope": "collective_leave",
      "nationwide": true,
      "subdivision_codes": []
    }
  ],
  "holidays": [
    {
      "date": "2026-08-17",
      "name": "Independence Day",
      "local_name": "Hari Kemerdekaan",
      "subdivision_codes": [],
      "nationwide": true,
      "observed": null,
      "scope": "national_public"
    }
  ]
}

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

حقول العطلات المشتركةلكل حدث قابلية تطبيق وطنية أو إقليمية محددة صراحةً.

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

أرسل طلبًا موثقًا واحدًا لـCPI الأمريكي، واقرأ الاستجابة وافهم أكثر أخطاء APIشيوعًا. 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. وتعيد التقاويم المفقودة أو غير الصالحة أو المسحوبة 503 calendar_coverage_unavailable.

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

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