العطلات في تاريخ

استرجع كل إجازة رسمية منشورة في تاريخ مدني محلي واحد.

طلب

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

GET /v1/calendars/holidays/{country}/on/{date}

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

المعلمات

الاسم	النوع	قاعدة
`country`	سلسلة نصية	قيمة مطلوبة في المسار. رمز ISO أبجدي ثلاثي واحد مدعوم بأحرف كبيرة، مثل IDN.
`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": []
    }
  ],
  "holidays": [
    {
      "date": "2026-08-17",
      "name": "Independence Day",
      "local_name": "Proklamasi Kemerdekaan",
      "subdivision_codes": [],
      "scope": "national_public"
    }
  ]
}

يُرجع جميع الأحداث المطابقة. تعني مصفوفة holidays الفارغة عدم وجود حدث مطابق ضمن سنة منشورة كاملة؛ ولا تثبت أن البنوك أو البورصات مفتوحة. يُرجع البلد والسنة غير المنشورين 404 calendar_not_published؛ ويُرجع فشل القراءة 503.

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

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

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "calendars_get_holidays_on_date",
    "arguments": {
      "country": "IDN",
      "date": "2026-08-17"
    }
  }
}

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

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

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