Calendar API

Appearance

CalendarAPIEasily expose your calendars via modern APIs.

CalendarAPI parses iCal (.ics) files and serves them over gRPC and REST. It supports hot config reloads via Viper and comes with a Home Assistant add-on.

Get Started →GitHub Releases →

Why CalendarAPI?

A modern, hackable API layer for your calendars.

Parse iCal (.ics) files from URLs or local paths

CalendarAPI reads `.ics` files directly from remote or local sources, keeping your workflow flexible.

Exposes events via REST and gRPC APIs

Modern API endpoints make it easy to query and integrate calendar data into any stack.

Rule engine for filtering and relabeling events

A powerful built-in engine to filter, relabel, and skip events based on your custom rules.

Hot config reloads via Viper

No restarts needed — changes to your config are picked up live using Viper.

Home Assistant Add-On

Easily deploy CalendarAPI into your smart home using the official HomeAssistant Add-On.

Custom status messages for displays

Set dynamic status messages per calendar — perfect for e-Paper displays or presence indicators.

CLI client for querying and scripting

Use the CLI to fetch calendars, set statuses, and integrate CalendarAPI into your shell workflows.

Minimal footprint, deploy anywhere

Lightweight Go binary runs on containers, Raspberry Pi, or any Linux host with minimal resources.

Releases

Select your platform

v0.1.9

Changelog

  • c2cc3ed chore(.gitignore): add __debug_bin* to ignore list to prevent clutter in the repository feat(launch.json): add new launch configuration for getting calendar data to streamline development feat(calendar.go): enhance calendar event formatting with styles for better readability fix(calendar.go): improve event sorting logic to handle simultaneous start times correctly fix(ical_client.go): enhance error logging with additional context for easier debugging refactor(ical_client.go): rename saveIcalParse to safeIcalParse for clarity in function purpose

v0.1.8

Release notes

Changelog

  • bc80097 feat(ical_client.go): add saveIcalParse function to encapsulate iCal parsing logic and improve error handling
  • b17d7fc style(serve.go): remove unnecessary blank line for improved code readability

v0.1.7

Release notes

Changelog

  • 15edbd2 feat(cmd): implement OpenTelemetry observability with logging and tracing for better monitoring and debugging refactor(cmd): simplify logging initialization and error handling in main.go fix(client): improve error logging and handling in ICalClient methods for better traceability chore(go.mod): update dependencies to latest versions for improved stability and security
  • b7305f5 s/Kienzler/Specht/
  • 808460b move links to main page
  • f22be48 chore(deps): update dependency @rollup/rollup-linux-x64-gnu to v4.42.0 (#81)
  • e79b621 fix(deps): update module google.golang.org/grpc to v1.73.0 (#82)
  • 994cc9b Potential fix for code scanning alert no. 1: Workflow does not contain permissions (#80)
  • 9a0005b fix buttons
  • 7c6c9a7 Update README.md
  • b46ebd0 fix getting started link
  • ae19090 fix pr triggers
  • 242ef7f fix pr triggers
  • c91cb60 fix(deps): update dependency lru-cache to v11 (#78)
  • 78a438d fix(deps): update dependency markdown-it-emoji to v3 (#79)
  • 0212997 bump npm versions
  • f2801e7 add social preview logo

v0.1.6

Release notes

Changelog

  • 584113c fix README.md
  • 3371d1f fix README.md
  • 876cdad golangci-lint
  • da75c04 fix npm i
  • 0f2d7f8 fix Vue components
  • 8ae9d6f use humane.Error
  • baa8258 use humane.Error
  • f9097b3 chore(deps): update dependency vue to v3.5.16 (#77)
  • 2e34472 switch logo
  • 70f6413 fix(deps): update dependency markdown-it-emoji to v3 (#75)
  • c80c672 chore(deps): update golangci/golangci-lint-action action to v8 (#58)
  • f695390 fix(deps): update dependency lru-cache to v11 (#74)
  • 2ff1d59 add specht-labs footer
  • 5c848bb fix workflow
  • a6402e5 fix workflow
  • 166832f fix workflow
  • 65d710f fix package.lock
  • 7175364 improve the docs
  • 831aac4 fix LICENSE
  • a752ff7 fix artifact name in deploy step
  • 8d62fcf add workflow_dispatch
  • b3c378b add Static Pages deployment
  • ca088c1 fix(deps): update module google.golang.org/grpc to v1.72.2 (#72)
  • 0c836c8 chore(deps): update dependency @rollup/rollup-linux-x64-gnu to v4.41.1 (#71)
  • 7809fd8 fix(deps): update opentelemetry-go-contrib monorepo to v0.61.0 (#70)
  • bc7c515 fix(deps): update opentelemetry-go monorepo to v1.36.0 (#69)
  • 1001af1 fix(deps): update module github.com/gin-gonic/gin to v1.10.1 (#68)
  • 1a64a02 chore(deps): update dependency @rollup/rollup-linux-x64-gnu to v4.41.0 (#67)
  • 850d3cb chore(deps): update dependency sass-embedded to v1.89.0 (#66)
  • 2d5534f fix(deps): update module google.golang.org/grpc to v1.72.1 (#65)
  • f5decff fix(deps): update module github.com/spechtlabs/go-otel-utils/otelzap to v0.0.10 (#64)
  • 29a7db8 fix(deps): update module github.com/spechtlabs/go-otel-utils/otelprovider to v0.0.10 (#63)
  • 58d9ad4 chore(deps): update dependency sass-embedded to v1.88.0 (#62)
  • 26a6263 fix(deps): update module github.com/spechtlabs/go-otel-utils/otelprovider to v0.0.9 (#61)
  • 20465d0 fix(deps): update module github.com/spechtlabs/go-otel-utils/otelzap to v0.0.9 (#57)
  • 1159882 fix(deps): update module github.com/spechtlabs/go-otel-utils/otelprovider to v0.0.8 (#60)
  • 026c5f6 update otelzap
  • 043c928 update otelzap
  • be9e7c3 update otelzap
  • a59c989 fix(deps): update module github.com/spechtlabs/go-otel-utils/otelprovider to v0.0.6 (#56)
  • 1ba8e72 fix golangci-lint
  • a344d99 chore(deps): update dependency @rollup/rollup-linux-x64-gnu to v4.40.2 (#59)

v0.1.4

Release notes

Changelog

  • d45f57f fix otel instrumentation
  • ac99e02 chore: simplify tracing (#55)
  • 8c96891 improve CI/CD
  • 008780d chore(deps): update dependency @rollup/rollup-linux-x64-gnu to v4.40.1 (#54)
  • feb4a48 chore(deps): update dependency sass-embedded to v1.87.0 (#53)
  • 441db29 fix(deps): update module google.golang.org/grpc to v1.72.0 (#52)
  • e4e4557 chore(deps): update dependency @rollup/rollup-linux-x64-gnu to v4.40.0 (#51)
  • f9e14bf chore(deps): update dependency @vuepress/theme-default to v2.0.0-rc.92 (#48)
  • f71ae4b fix(deps): update module github.com/fsnotify/fsnotify to v1.9.0 (#47)
  • a6956b5 chore(deps): update dependency @rollup/rollup-linux-x64-gnu to v4.39.0 (#45)
  • b85181f chore(deps): update dependency sass-embedded to v1.86.3 (#46)
  • 442a423 fix(deps): update module google.golang.org/grpc to v1.71.1 (#44)
  • c14ef05 fix(deps): update module github.com/gin-contrib/zap to v1.1.5 (#43)
  • 0f52f47 chore(deps): update dependency @vuepress/theme-default to v2.0.0-rc.91 (#42)
  • 07571c0 chore(deps): update dependency sass-embedded to v1.86.1 (#41)
  • 070e167 enable id-token: write for GHP deployment
  • c267a38 enable github pages
  • 030f58a Add documentation (#40)
  • b8ac480 bump yaml to v3
  • c85e528 move source code in src/ directory (#39)
  • a3512fc fix(deps): update module github.com/spf13/viper to v1.20.1 (#38)

Contributors

Your contributions matter. Here's to everyone who's helped bring this to life.