Google Calendar API は、Google カレンダーの予定をプログラムから作成・更新・削除するための API だ。スケジュール管理を自前で実装する代わりに、すでに多くのユーザーが日常的に使っているカレンダーに乗せられるのが大きい。

予約システムとの相性

代表的な活用先は予約システムだ。予約が入ったら API でカレンダーにイベントを作り、変更や取り消しも同期させる。フリー／ビジー情報を取得できるので「空いている時間だけを予約候補として見せる」処理も組める。プッシュ通知を使えばカレンダー側の変更をアプリが検知でき、ポーリングに頼らない設計が可能になる。繰り返し予定の扱いも API でサポートされている。

繰り返し予定という難所

実装で手こずりやすいのが繰り返し予定だ。「毎週月曜」のような定期イベントは一つのレコードとして表現される一方、その中の特定の一回だけを変更・削除した「例外」インスタンスは別扱いになる。予約システムでこれを正しく処理しないと、ある日の予定だけ消したつもりがシリーズ全体に影響する、といった事故につながる。例外インスタンスの考え方を最初に押さえておきたい。

料金とクォータ

個人の Google アカウントで無料利用でき、API 呼び出しはデイリークォータ制。一般的なアプリの使い方なら枠は十分に広く、コストを気にする場面は少ない。ただしクォータ超過時のエラーハンドリングは実装しておきたい。タイムゾーンの扱いもバグの温床で、イベントの日時には必ずタイムゾーンを明示し、サーバーのロケールに依存させないことが安全だ。

向かない組織

前提として、ユーザーが Google カレンダーを使っていることが必要になる。社内で Microsoft 365 を標準にしている組織のスケジュール管理を作るなら、Calendar API ではなく Microsoft Graph 側を見るべきだ。導入対象のユーザー層がどのカレンダーを使っているかを最初に確認しておくと、土台選びを間違えずに済む。

タイムゾーンの扱いが不具合の温床

カレンダーの予定は、日時とタイムゾーンの組み合わせで意味が決まる。サーバーの時刻設定、利用者の所在地、カレンダー自体のタイムゾーン設定が食い違うと、予定が数時間ずれて登録される。とくに終日予定と時刻指定の予定では扱いが異なり、日付だけで表す終日予定を時刻付きとして処理すると前後の日にずれる。時刻を扱うコードでは、必ずタイムゾーンを明示した形式で受け渡すべきだ。

💡
変更の検知はポーリングより通知チャネルが有利です

予定の変化を追うために定期的に一覧を取得すると、クォータを消費し続けます。変更通知を受け取る仕組み（Push Notification）を使えば、変化があったときだけ処理できます。通知には有効期限があるため、期限前に更新する処理を忘れないでください。

権限の範囲をユーザーに説明する

カレンダーへのアクセスは、利用者にとって心理的な抵抗が大きい領域だ。読み取りだけで足りるのか、書き込みまで要るのか、対象は特定のカレンダーだけかを設計で絞り、同意画面で何を求めているかが伝わるようにしておく。過大な権限を求めるとインストール率が下がるだけでなく、組織の管理者に承認を止められる要因にもなる。