Cal-Bridge

Stop screenshotting your e-Bridge timetable and setting it as your phone's wallpaper.

Cal-Bridge converts it into an ICS file you can import into Google Calendar, Outlook, Apple Calendar, and any other standard calendar app — so your schedule is always with you, live alongside the rest of your life.

🚀 Quick Start

1. Clone and install

git clone https://github.com/your-username/cal-bridge.git
cd cal-bridge
python -m venv .venv

.venv\Scripts\activate          # Windows
source .venv/bin/activate       # macOS / Linux

pip install -r requirements.txt

2. Get your personal API URL

The timetable data is served from a personal API endpoint. The URL contains a hash unique to your enrollment — you need to find it once:

1. Open E-Bridge and log in.
2. Click Timetables in the left sidebar → Navigate to My Personal Class Timetable.
3. Press F12 → Network tab → type activity in the filterbox.
4. Reload the page. Click the request that appears and copy Request URL value. This URL should look like:

https://timetableplus.xjtlu.edu.cn/ptapi/api/enrollment/hash/{YOUR_HASH}/activity

This URL is personal to you — do not share it publicly.

3. Configure

cp config.template.json config.json

Open config.json and paste your URL into api.base_url to replace the placeholder:

{
  "api": {
    "base_url": "paste_your_URL_here_with_quotes_retained"
  },
  "calendar": {
    "end_buffer_enabled": true,
    "end_buffer_minutes": 10
  },
  "timezone": "Asia/Shanghai",
  "week_indicator": {
    "enabled": false,
    "day_of_week": "Monday"
  }
}

4. Run

python __main__.py

The generated ICS file is written to output/:

output/Timetable_{current_year_semester}_{timestamp}.ics

⚙️ Configuration

config.json

Key	Description
api.base_url	Your personal TimetablePlus API URL.
calendar.end_buffer_enabled	If true, follow e-Bridge display method to trim minutes from each class end time to create buffer time for moving between venues.
calendar.end_buffer_minutes	Number of minutes to trim from each class end time (only applied when end_buffer_enabled is true).
timezone	IANA timezone name for all calendar event times. Defaults to Asia/Shanghai, reference here.
week_indicator.enabled	If true, adds an all-day "Week X" event for each teaching week. Defaults to false.
week_indicator.day_of_week	The day the indicator event is placed on (Monday–Sunday). Defaults to Monday.

week_mapping.json

Maps each teaching week number to its ISO calendar week, which is how Cal-Bridge resolves abstract teaching weeks (e.g. "Week 4") to real calendar dates. The file ships with a mapping for the current semester.

Teaching weeks do not always map to consecutive ISO weeks because university recesses (e.g. National Holiday) create gaps.

Note that the teaching_start_date and teaching_end_date are deprecated fields, for reference only.

This file is expected to be updated at the start of each semester, otherwise ICS file generated will be incorrect. Contributions are welcome.

{
  "current_semester": "ay2526-s1",
  "ay2526-s1": {
    "teaching_start_date": "2025-09-08",
    "teaching_end_date": "2025-12-12",
    "teaching_weeks": {
      "1":  {"iso_week": 37, "year": 2025},
      "...": "..."
    }
  }
}

CLI arguments

All arguments are optional — defaults work out of the box.

python __main__.py [--config PATH] [--week-mapping PATH] [--output DIR]

Argument	Default	Description
--config	config.json	Path to the configuration file.
--week-mapping	week_mapping.json	Path to the week mapping file.
--output	output/	Directory where the ICS file will be written.

🔍 How it works

The E-Bridge timetable page embeds TimetablePlus in an iframe, which fetches your timetable as structured JSON from a personal API endpoint. Cal-Bridge hits that same endpoint directly and runs it through a three-stage pipeline:

1. Fetch — pulls your timetable entries from the API and validates the response.
2. Parse — each entry describes a class recurring across multiple teaching weeks (e.g. "1-3, 5, 8-12"). Cal-Bridge expands these into individual dated events by mapping teaching weeks to real calendar dates via week_mapping.json. University recesses (e.g. National Holiday) mean teaching weeks don't always fall on consecutive calendar weeks — the mapping accounts for these gaps.
3. Generate — writes all events to a standards-compliant .ics file, with timezone info included so any calendar app can import it correctly.

📁 Project structure

cal-bridge/
├── __main__.py          # Entry point: python __main__.py
├── config.template.json # Template for config.json
├── week_mapping.json    # Teaching-week → ISO-week mapping table
├── requirements.txt     # Python dependencies
├── output/              # Generated ICS files
└── src/
    ├── config.py        # Loads and validates config.json + week_mapping.json
    ├── fetcher.py       # Fetches and validates data from the TimetablePlus API
    ├── parser.py        # Normalizes entries and resolves dates
    ├── generator.py     # Writes the ICS file
    └── main.py          # Pipeline orchestrator