システムで祝日の判定を使用することは、多くのエンジニアが一度は通る道ではないか思います。
自分もついにその判定を実装することになったので、どのように実装するべきか、あらためて Web 上の情報をまとめました。
実装の方針
祝日の判定方法には、大きく 3 種類の方針があります。
- 元データを入手して独自に API やライブラリを実装する
- Web API を判定のたびに叩く
- ライブラリを使う
以下、この 3 つの方針について順に解説していきます。
元データを入手して独自に API やライブラリを実装する
まずは何らかの方法で祝日一覧のデータを入手して、それを元に API やライブラリ (または関数など) を実装する方法についてです。
祝日を判定する API やライブラリを独自実装する場合、元データをどこから入手するのかという問題があります。
元データの取得元としては、大きく 2 パターンあります。
- 内閣府の「国民の祝日について」
- Google Calendar API
の 2 つです。
内閣府の「国民の祝日について」
日本における国民の祝日について、内閣府の Web サイトの「国民の祝日について」というページで解説されています。
このページからは国民の祝日の一覧が CSV 形式でダウンロード可能で、プログラムなどで祝日を判定する際の元データとして利用可能です。
このデータを使う場合、祝日の判定のたびに内閣府の Web サイトにアクセスするのはよろしくないため、自前で CSV データ (またはそれを変換したデータ) を管理する必要があります。
内閣府の「国民の祝日について」のデータを元データとして使うメリット・デメリットは以下のようになります。
メリット
- 内閣府が正式に出しているデータなので、データの信頼性が非常に高い
デメリット
- 1 年ごとなど、定期的に最新の CSV をダウンロードしてマスタデータを更新する必要がある (さらに言えば、URL や CSV のフォーマットが変更になる可能性があるため、マスタデータの更新作業を自動化することは難しい)
- CSV のフォーマットが変更になる可能性が低くないため、CSV をパースするプログラムを適宜修正する必要性が発生しうる (また、過去に不適切なフォーマットの CSV が提供されていたこともあり、プログラムから使いやすくない形式に変更される可能性もある)
参考
- 正確でカスタマイズ可能な日本の祝日・休日判定処理を求めて
- 【悲報】内閣府の「国民の祝日」CSVがひどいと話題に【更新】
- [PHP] 内閣府から提供されている祝祭日CSVデータを読み込んで休日を判断する
- 【Python】休日または祝日を判定する
Google Calendar API
続いて、Google Calendar API を使って祝日のデータを取得する方法です。
Google Calendar API は Google が提供する API の 1 つで、ここから日本の祝日を取得することができます。
利用するには API にアクセスするためのトークンを払い出し、リクエスト時に送信する必要があります。
Google Calendar API を元データとして使うメリット・デメリットは以下のようになります。
メリット
- 内閣府の「国民の祝日について」と異なり、定期的に最新のデータをダウンロードする必要がない
- 内閣府の「国民の祝日について」よりはデータ形式やインタフェースが変更になる頻度が低いと想定される
- もしデータ形式やインタフェースが変更になる際は、メールなどで通知されることが期待できる
デメリット
- 実務においては、API キーを払い出す際のプロジェクト管理について考慮する必要が出る
- API キーを何らかの方法で管理する必要がある
参考
Web API を判定のたびに叩く
次に、祝日の判定に Web API を判定のたびに叩く方法です。
祝日の判定が必要になるたびに API を叩く方針にすることで、元データをどこかに保存する手間を省いたり、判定ロジックの実装を不要化または簡易化することが可能になります。
一方、判定のたびに API を叩く場合、レートリミットやサービスレベルに注意する必要があります。 また、独自実装やライブラリの使用と異なり、インターネットを経由した通信が発生するため、レイテンシを許容する必要も出てきます。
ざっと調べた範囲では、祝日の判定に使える Web API として
- Google Calendar API
- Holidays JP API
- 祝日判定web API
の 3 つが見つかりました。
Google Calendar API
Google Calendar API は、上に書いたように元データの取得元として使うのではなく、祝日の判定が必要になるたびに叩くことも可能です。
他の API と比べたメリット・デメリットは以下のようになります。
メリット
- レートリミットについて「Google Calendar API Usage Limits」のページに公式に書かれている
- SLA に関する記述は見つからないものの、Google が提供しているためある程度のサービスレベルが期待できる
デメリット
- 実務においては、API キーを払い出す際のプロジェクト管理について考慮する必要が出る
- API キーを何らかの方法で管理する必要がある
ちなみに、Google Calendar API は GAS からだと非常に簡単に使えます。
参考
Holidays JP API
Holidays JP API は、Google Calendar API を元データとして提供されている API です。
Google Calendar API のデータを祝日の判定に使いやすい形式に変換したものと考えてください。
メリット
- Google Calendar API よりシンプルに使える
- API キーを管理する必要がない
- ソースコードが公開されているため、バグがないかなどをチェックできる
デメリット
- 個人が開発した API のため、Google Calendar API と比べると信頼性は劣る
- ホスティングされている GitHub Pages の障害が少なくない (GitHub のステータスページ を参照のこと)
参考
祝日判定web API
祝日判定web API は、内閣府の Web データを元に提供されている API で、APIbank にも登録されています。
メリット
- Google Calendar API よりシンプルに使える
- API キーを管理する必要がない
- 国民の祝日だけでなく、官公庁や株式市場の休みにも対応している
デメリット
- SSL 証明書の有効期限が切れており、HTTPS ではなく HTTP での通信が前提となっている
- どの程度のアクセスに耐えうるのか不明
- データの誤りやサービスの継続性について免責されており、サービスレベルを期待しにくい
ライブラリを使う
最後に、各プログラミング言語のライブラリを使う方法です。
- JavaScript … date-holidays
- Ruby … 日本の祝日判定Rubyプログラム
など、各種プログラミング言語で祝日判定用のライブラリが存在するようです。
こういったライブラリを使えば、元データを独自に加工するプログラムを書く必要もありませんし、Web API を使う場合のようにレートリミットやサービスレベル、レイテンシなどを気にする必要もありません。
ただし、祝日データを更新するため、定期的にライブラリをバージョンアップするなどの対応が必要になります。 ライブラリのバージョンアップが必要な日が迫ったらアラートが上がるようにしておくといいかもしれません。
結論
以上を踏まえて、祝日の判定についてどの方法を採用すべきか、自分の考えをまとめます。
使用している言語に信頼できる祝日判定ライブラリがある場合
まず、使用している言語に信頼できる祝日判定ライブラリがある場合、ライブラリの利用を第一に考えるべきでしょう。
他の方法と比べて実装コストがはるかに低いうえ、Web API を使う場合のようにレートリミットやサービスレベル、レイテンシなどを気にする必要もありません。
ただし、ライブラリを使う場合はバージョンアップが必要な日が迫ったらアラートが上がるような仕組みを入れておくと良さそうです。
ライブラリが見つからず、レートリミットやサービスレベル、レイテンシが気にならない場合
良さそうなライブラリが見つからなかった場合、独自実装か Web API のどちらかを選ぶことになります。
個人開発など、祝日の判定の頻度が低く、レートリミットやサービスレベル、レイテンシも気にならないといった場合は、Web API を必要なタイミングで叩く方法でいいのではないかと思います。
どの API を使うかという観点では、Google Calendar API が信頼度が高いですが、より簡易的に済ませたい場合は Holidays JP API でもいいと思います。
ライブラリが見つからず、レートリミットやサービスレベル、レイテンシについて気にかけたい場合
レートリミットやサービスレベル、レイテンシについて気にかけたい場合は、内閣府の「国民の祝日について」か Google Calendar API を元データとして独自実装することになります。
実務上は、API を適宜叩くよりも、この選択をとることが多くなると思います。
Google Calendar API を使う際の API キーの管理の手間も考えると、内閣府の「国民の祝日について」のデータの方が気軽に使えます。
祝日のマスタデータを登録する仕組みだけシステムに用意しておいて、年に一度程度マスタデータを更新する方針でも十分でしょう。
