【ITニュース解説】Building hldays #4: Business days that know local holidays

ソフトウェア開発において「今日が稼働日かどうか」「N営業日後がいつか」という情報は、一見シンプルに見えても、実は非常に複雑な問題を含んでいる。国全体が休みでなくても、ある都市だけが独自の祝日で閉まっているといった状況は珍しくない。ポルトのサン・ジョアンの例では、全国的な祝日ではないにもかかわらず、その市町村では公共機関が閉鎖され、通常の稼働日とは異なる扱いになる。このような地域固有の休日を考慮しないと、システムが誤った判断をしてしまう可能性がある。

このような複雑な日付計算を解決するために、「hldays」というAPIサービスが提供されている。hldaysは、国、地域、さらには市町村レベルの独自の休日まで考慮して、正確な稼働日情報を教えてくれる。このサービスには主に二つの機能が用意されている。一つは、特定の日付がビジネスデー（稼働日）であるかどうかを判定する「/v1/business-day」というエンドポイントで、もう一つは、特定の日付から数えてN営業日後の日付を計算する「/v1/business-days/add」というエンドポイントである。

これらのエンドポイントは、国や地域のID（例: PT-M-1312）や名前（例: porto）を指定することで利用できる。hldaysの内部では、指定された地域だけでなく、その地域が属する上位の地域（国や州など）の休日も自動的に継承して、最終的な稼働日を判断する仕組みになっている。例えば、イギリスのイングランドで2026年12月28日を調べると、この日はクリスマスの振替休日（Boxing Day）で稼働日ではないと判定される。APIからの応答には、その日が週末ではないこと、そして「Boxing Day」という休日が2026年12月26日の振替であることなどの詳細情報が含まれており、なぜ稼働日ではないのかが明確にわかるようになっている。また、12月24日から2営業日後を計算すると、クリスマスや週末、そして振替休日を飛ばして12月30日になる、といった正確な計算が行われる。

hldaysの内部コードは、シンプルな構造を保つように設計されている。稼働日を判定する「isBusinessDay」という関数は、指定された管轄地域と日付を受け取り、その日が週末ではないか、また休日リストに含まれていないかをチェックする。週末の定義は国ごとに設定されており、例えばイギリスでは土曜日と日曜日が週末として定義されている。将来的に金曜日と土曜日を週末とする国が追加されても、コードの修正なしに柔軟に対応できる設計だ。営業日を加算する「addBusinessDays」という関数は、開始日から一日ずつ日付を進めていき、それぞれの日に「isBusinessDay」関数を使って稼働日かどうかを判定し、必要な営業日数に達するまでこの処理を繰り返す。この一見単純なループ処理は、複雑な振替休日や地域固有の休日を考慮した際に、変にショートカットを試みるよりも信頼性が高いため、あえてシンプルに保たれている。パフォーマンスについては、高負荷な処理（地域の休日ルールを年ごとに展開する処理）がキャッシュされるため、二回目以降のアクセスは高速である。

休日の中には、週末と重なると別の日に移動する「振替休日」というものがある。例えば、アメリカ合衆国では、元旦が土曜日に当たると前日の金曜日に、日曜日に当たると翌日の月曜日に振替られる。hldaysでは、このような振替休日を正しく処理するために、指定された年の休日だけでなく、前後の年の休日も内部的に展開して計算する。これにより、元旦が前年の大晦日に振替られるようなケースでも、正確にその日が稼働日ではないと判定できる。

休日はその性質によって、「public（公共の休日）」、「local（市町村などの地域休日）」、「optional（任意休日）」といった種類に分けられる。hldaysでは、デフォルトで公共の休日と地域の休日を考慮して稼働日を判定するが、APIのリクエスト時に「types」パラメータを指定することで、どの種類の休日を考慮するかをカスタマイズできる。これにより、例えば企業が市町村の休日に従業員を働かせたい場合、地域の休日を除外して稼働日を計算することが可能になる。

hldaysには、利用プランに応じた機能の違いもある。無料プランでは、市町村レベルの地域固有の休日が計算に含まれない。そのため、ポルトのサン・ジョアンの日のように、有料プランでは稼働日ではないと判定される日が、無料プランでは稼働日と判定されることがある。しかし、無料プランの応答には、市町村レベルの休日が考慮されていない旨の注意書き（notice）が明示されるため、ユーザーは提供された情報が完全ではないことを認識できる。これは「間違った回答」を提供するのではなく、「少し異なる質問に対する正しい回答」を提供するという思想に基づいている。アプリケーションを開発する際には、この注意書きを確認し、必要に応じてユーザーに情報を提示するなどの対応を検討することが重要になる。

hldaysは、実装にあたっていくつかのエッジケース（特殊な状況）も考慮している。例えば、営業日を加算する際に開始日自体はカウントせず、次の営業日から数え始める。負の値を指定すれば過去に遡って営業日を計算できる。また、「0日」を指定した場合は開始日がそのまま返され、それが休日であっても自動的に次の稼働日に移動することはない。一度のリクエストで計算できる営業日数には上限（-366日から366日）が設けられている。年をまたぐ計算も正しく行われ、翌年の休日も考慮される。ただし、APIがサポートする日付の範囲は2016年から2099年までであり、この範囲外の計算結果になる場合はエラーが返される。また、無効な日付（例: 2月30日）はエラーとして処理され、自動的に修正されることはない。

一方で、hldaysが提供しない機能もある。例えば、クリスマスイブの午後といった「半日休み」はモデル化されていない。また、会社独自の休日を追加してカスタマイズする機能も提供されていない。さらに、宗教的・文化的な「観測日」（例: イード、過ぎ越しの祭り、旧正月など）は、APIの応答でリスト化される場合があるものの、それ自体が日を稼働日ではないと判定する要素にはならない。

このように、hldaysは一見シンプルな「稼働日とは何か」という問いに対し、地域性、振替休日、休日の種類、料金プランの差異、様々なエッジケースまで考慮した、複雑で実用的な解決策を提供している。システムエンジニアにとって、このような外部APIの活用は、自社でゼロから複雑な日付計算ロジックを開発・維持する手間を省き、より本質的なビジネスロジックの開発に集中できるという大きなメリットがある。