/ˈtɹænzɪ.kæl/

transical converts publically-available GTFS transit schedules into calendar events, bundled into iCalendar (.ics) files.

It’s designed to automate putting public transit schedules in your calendar. iCalendar files can be imported into Google Calendar, Apple Calendar, Evolution, Thunderbird, or just about any other calendar application.

installing

pipx is the preferred way to install transical. Unlike pip alone: it automatically isolates the package from your other Python packages, puts the package in your PATH, and installs manpages.

On pipx systems:

pipx install transical

Install shell autocompletions with transical --autocomplete.

do you really want to use pip?

pip is not recommended. On pip systems, for global installation:

pip install transical

usage

transical input.gtfs 2026-07-01/2026-08-01 output.ics

That's it! transical interactively walks you through picking a route, origin stop, and destination stop, before producing an output file with all the transit journeys that fall between the specified dates.

$ transical https://feeds.mta.maryland.gov/gtfs/marc 2026-07-01/2026-08-01 output.ics
No route was provided. Use arrow keys to select a route from the menu below.
🔄› 11704 · MARC · BRUNSWICK - WASHINGTON                                       
    11705 · MARC · PENN - WASHINGTON                                            
    11706 · MARC · CAMDEN - WASHINGTON                                          
Selecting route. Hit </> to search.

You can directly import transical's .ics outputs in desktop applications (guides linked) like Google Calendar, Apple Calendar, Evolution, and Thunderbird.

You can also send outputs to yourself to import events on another device, with a tool like xdg-email:

xdg-email --attach output.ics recipient@example.com

more features

transical supports adding event reminders, and it even has its own filtering language to let you granularly choose journeys based on time of day and day of week.

transical has a noninteractive, script mode, too; it won't output anything it doesn't need to when called with --route and --termini flags already provided to it.

Read more about using transical or writing filter expressions. You can also find this documentation in transical's manpages, or see an overview with transical --help.

developing and building

This project uses uv.

Clone the repository with Git and use uv to install dependencies:

git clone git@github.com:solanto/transical.git
cd transical
uv sync

Run the program in development with uv run:

uv run transical

And build the package with uv build:

uv build

This not only packages the program itself, but also converts documentation in docs to manpages—installable via pipx—by way of a custom Pandoc pipeline. You can check out this pipeline in tools.

acknowledgements

komoot's free photon API for OpenStreetMap lets this project make station names prettier in your calendar. Thanks, komoot!

contributing

Feel free to ask questions or make suggestions here or at person@dandelion.computer. I'll do my best to collaborate with those who'd like to!

If you fork transical, be sure to change meta:ORG_DOMAIN to your own domain (which could even be something like your-username.github.io). transical uses this identifier to tell remote servers exactly whose code is requesting information, as well as to document exactly whose code made the events in produced iCalendar files.

license

GNU General Public License v3.0 or later. See license in LICENSE.md.