ドキュメント
祝日を一覧表示
1つの国と年について、公開済みの完全なカレンダーを取得します。
リクエスト
Narwhalキーで公開済みの国・年について利用できます。 カバレッジと適用範囲 を、日付を指定してリクエストする前に確認してください。
GET /v1/calendars/holidays/{country}/{year}curl "https://api.narwhalapi.com/v1/calendars/holidays/IDN/2026" \
-H "Authorization: Bearer $NARWHAL_API_KEY"パラメータ
| 名前 | 種別 | 規則 |
|---|---|---|
country | 文字列 | 必須パス値。IDN など、サポート対象の大文字 ISO alpha-3 コードを1つ指定します。 |
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"
}
]
}公開済みの1年分のデータ全体を日付と名前の順に並べて返し、日付と名前が同じ場合も並び順は一定です。同じ日の異なる祝日は別々に扱います。ページ分割はありません。例は1件のイベントを示すもので、完全なカレンダーではありません。
共有休日フィールド。各イベントには、国または地域への適用範囲が明示されます。
対応する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。
年、日付、または範囲がプランの履歴対象期間（Freeは12か月、Basicは5年、Proは全期間）より前の場合は403 plan_upgrade_requiredを返します。
成功した呼び出し1回で、イベント数や読み取る年数にかかわらず、月間リクエストを1件消費します。エラーでは月間クォータを消費しません。 共有エラーの詳細。