Shogo's Blog

Sep 4, 2021 - 2 minute read - aws github

祝日APIを公開しました

プログラマーなら誰しも一度は祝日について頭を悩ませたことがあるでしょう(要出典)。

日付が固定ならまだ楽なんですが、「春分の日」「秋分の日」のように天体の運行によって決まる祝日があったり、 ハッピーマンデー制度によって「成人の日(一月の第二月曜日)」のような曜日固定の祝日があったり、 振替休日という概念があったりと、ちゃんと考えるとかなり面倒です。

更に面倒なのが国の施策によってたまに変更になるという点です。 東京オリンピックの延期で祝日が移動したのは記憶に新しいですね。 前年の 12 月 4 日に法律が公布されるという、カレンダーの印刷会社泣かせなスケジュール変更です。

プログラムなら更新可能ですが、ライブラリとして組み込まれているとうっかり更新を忘れてしまうこともありますよね。 そういうわけで API として提供されていると嬉しいな、プログラミング言語に縛られることもないし、ということで作りました。

使い方

パスに日付を入力して GET リクエストを投げるだけのシンプルな API です。

ある年の祝日一覧を取得する

GET /{year} で year の祝日一覧を返します。 以下は 2021 年の祝日一覧を返す例です。

curl https://holidays-jp.shogo82148.com/2021 | jq .
{
  "holidays": [
    {
      "date": "2021-01-01",
      "name": "元日"
    },
    {
      "date": "2021-01-11",
      "name": "成人の日"
    },
    {
      "date": "2021-02-11",
      "name": "建国記念の日"
    },
(snip)
    {
      "date": "2021-11-23",
      "name": "勤労感謝の日"
    }
  ]
}

ある月の祝日一覧を取得する

GET /{year}/{month} で月の祝日一覧を返します。 以下は 2021 年 1 月の祝日一覧を返す例です。

curl https://holidays-jp.shogo82148.com/2021/01 | jq .
{
  "holidays": [
    {
      "date": "2021-01-01",
      "name": "元日"
    },
    {
      "date": "2021-01-11",
      "name": "成人の日"
    }
  ]
}

ある日が祝日か調べる

GET /{year}/{month}/{day} でその日が祝日か調べることができます。 年・月とレスポンスの形式をあわせるために、必ず配列形式で返ってきます。 配列の件数で祝日・平日を判断してください。

祝日の例:

curl https://holidays-jp.shogo82148.com/2021/01/01 | jq .
{
  "holidays": [
    {
      "date": "2021-01-01",
      "name": "元日"
    }
  ]
}

平日の例:

curl https://holidays-jp.shogo82148.com/2021/02/01 | jq .
{
  "holidays": []
}

実装

最近マイブームな Amazon API Gateway + AWS Lambda による実装です。 AWS の設定管理には AWS Serverless Application Modelを利用しています。

データーソースには 2017 年の登場時にちょっと話題になった syukujitsu.csv を利用しています。

2021-09-04 現在 syukujitsu.csv には昭和 30 年（1955 年）から令和 4 年（2022 年）までの祝日が含まれています。 この期間に関しては CSV から検索して祝日を返しています。 2023 年以降に関しては 国民の祝日に関する法律 をもとに計算して求めています。

さて、真面目に計算しているおかげで法律の改正まではうまく動く想定でいますが、 syukujitsu.csv が更新されたら改正がないかチェックしたいですね。 色々考えた結果 Amazon EventBridge のスケジュールイベント をトリガーにして、 AWS Lambda → GitHub Repository dispatch → GitHub Actions で更新チェック、という形にしました。 ちょっと複雑ですね。なんでこんな面倒な構成に？とみなさん疑問を持つと思います。

syukujitsu.csv の定期更新はすでに先人がいるのですが、彼らの更新チェッカーを参考にした上でこうしました。

無料で使える範囲だとサービスの都合で CRON ジョブが止められる可能性があるんですね・・・。 ただより高いものはない、ということで多少お金をかけてでもジョブが止まらないように工夫した結果が先の構成です(とは言っても 1 円/月もかからないと思ってる)。 ただし動かしたばかりなので、いつまでノーメンテで動き続けるかは要観察です。

まとめ

祝日 API を公開しました。

できたてホヤホヤですが、ぜひご利用ください。

参考