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

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

طلب

متاح للسنوات والدول المنشورة باستخدام مفتاح 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. احذفه لإعادة جميع الفئات المنشورة.

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

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

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

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

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

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

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

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

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