Feat: Translink API

.github/workflows/pytest_unit.yml

@@ -13,20 +13,12 @@ jobs:
         with:
           python-version: '3.13'
 
-      - uses: actions/cache@v5
-        id: cache
+      - uses: astral-sh/setup-uv@v6
         with:
-          path: ~/.cache/pip
-          key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.*') }}
-          restore-keys: |
-            ${{ runner.os }}-pip-
+          enable-cache: true
 
       - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          python -m venv venv
-          source ./venv/bin/activate
-          pip install ".[test]"
+        run: uv sync --extra test --locked
 
       - name: Run unit tests
-        run: PYTHONPATH=src ./venv/bin/python -m pytest ./tests/unit -v
+        run: uv run pytest ./tests/unit -v

.gitignore

@@ -16,3 +16,4 @@ wheels
 
 .venv
 .DS_Store
+.env

pyproject.toml

@@ -12,22 +12,23 @@ dependencies = [
     "asyncpg==0.31.0",
     "alembic==1.18.4",
     "google-api-python-client==2.194.0",
-
     # minor
     "xmltodict==0.13.0",
     "httpx==0.28.1",
+    "pydantic-settings==2.14.1",
+    "gtfs-realtime-bindings==2.0.0",
+    "pandas==3.0.3",
 ]
 
 [project.optional-dependencies]
 dev = [
     "ruff==0.15.12", # linting and formatter
-    "pre-commit"
+    "pre-commit",
 ]
 
 test = [
     "pytest", # test framework
     "pytest-asyncio",
-    "httpx",
 ]
 
 [project.urls]

src/alembic/env.py

@@ -13,6 +13,7 @@
 import officers.tables
 import candidates.tables
 import event.tables
+import translink.tables
 from alembic import context
 
 # this is the Alembic Config object, which provides

src/alembic/versions/401b254a02a5_merge_events_and_translink_branches.py

@@ -0,0 +1,26 @@
+"""Merge events and translink branches
+
+Revision ID: 401b254a02a5
+Revises: 42f855bec532, c1a70c8cfd64
+Create Date: 2026-06-07 12:25:14.294686
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+
+
+# revision identifiers, used by Alembic.
+revision: str = '401b254a02a5'
+down_revision: Union[str, None] = ('42f855bec532', 'c1a70c8cfd64')
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    pass
+
+
+def downgrade() -> None:
+    pass

src/alembic/versions/c1a70c8cfd64_create_translink_static_schedule.py

@@ -0,0 +1,35 @@
+"""Create TransLink static schedule
+
+Revision ID: c1a70c8cfd64
+Revises: 0a2c458d1ddd
+Create Date: 2026-05-17 16:17:26.176355
+
+"""
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+from sqlalchemy.dialects import postgresql
+
+# revision identifiers, used by Alembic.
+revision: str = 'c1a70c8cfd64'
+down_revision: Union[str, None] = '0a2c458d1ddd'
+branch_labels: Union[str, Sequence[str], None] = None
+depends_on: Union[str, Sequence[str], None] = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table('translink_static_schedule',
+    sa.Column('id', sa.Integer(), nullable=False),
+    sa.Column('date_fetched', sa.Date(), nullable=False),
+    sa.Column('schedule', postgresql.JSONB(astext_type=sa.Text()), nullable=False),
+    sa.PrimaryKeyConstraint('id', name=op.f('pk_translink_static_schedule'))
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_table('translink_static_schedule')
+    # ### end Alembic commands ###

src/alembic/versions/f0c99d0db277_create_translink_realtime_cache.py

@@ -0,0 +1,36 @@
+"""Create TransLink realtime cache
+
+Revision ID: f0c99d0db277
+Revises: 401b254a02a5
+Create Date: 2026-06-26 16:54:33.26523
+
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers, used by Alembic.
+revision: str = "f0c99d0db277"
+down_revision: str | None = "401b254a02a5"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.create_table(
+        "translink_realtime_cache",
+        sa.Column("id", sa.Integer(), nullable=False),
+        sa.Column("fetched_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("response_bytes", sa.LargeBinary(), nullable=False),
+        sa.PrimaryKeyConstraint("id", name=op.f("pk_translink_realtime_cache")),
+    )
+    # ### end Alembic commands ###
+
+
+def downgrade() -> None:
+    # ### commands auto generated by Alembic - please adjust! ###
+    op.drop_table("translink_realtime_cache")
+    # ### end Alembic commands ###

src/auth/urls.py

@@ -3,7 +3,6 @@
 import os
 import urllib.parse
 
-import httpx
 import xmltodict
 from fastapi import APIRouter, BackgroundTasks, HTTPException, Request, Response
 from fastapi.responses import JSONResponse, RedirectResponse

src/config.py

@@ -0,0 +1,10 @@
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env")
+
+    translink_api_key: str | None = None
+
+
+settings = Settings()

src/database.py

@@ -5,8 +5,7 @@
 from typing import Annotated, Any
 
 import asyncpg
-import httpx
-from fastapi import Depends, FastAPI
+from fastapi import Depends
 from sqlalchemy import MetaData
 from sqlalchemy.ext.asyncio import AsyncConnection, AsyncSession, async_sessionmaker, create_async_engine
 from sqlalchemy.orm import DeclarativeBase
@@ -100,26 +99,14 @@ async def session(self) -> AsyncGenerator[AsyncSession]:
 def setup_database():
     global sessionmanager
 
+    db_url = SQLALCHEMY_TEST_DATABASE_URL if os.environ.get("ENV") == "test" else SQLALCHEMY_DATABASE_URL
     # TODO: where is sys.stdout piped to? I want all these to go to a specific logs folder
     sessionmanager = DatabaseSessionManager(
-        SQLALCHEMY_TEST_DATABASE_URL if os.environ.get("LOCAL") else SQLALCHEMY_DATABASE_URL,
+        db_url,
         {"echo": True},
     )
 
 
-@contextlib.asynccontextmanager
-async def lifespan(app: FastAPI):
-    """
-    Handles startup and shutdown events, see https://fastapi.tiangolo.com/advanced/events/
-    """
-    app.state.http_client = httpx.AsyncClient()
-    yield
-    await app.state.http_client.aclose()
-    if sessionmanager._engine is not None:
-        # Close the DB connection
-        await sessionmanager.close()
-
-
 async def get_db_session():
     async with sessionmanager.session() as session:
         yield session

src/load_test_db.py

@@ -26,6 +26,7 @@
     update_officer_term,
 )
 from officers.tables import OfficerInfoDB, OfficerTermDB
+from translink.tables import TransLinkStaticScheduleDB
 
 
 async def reset_db(engine):

src/main.py

@@ -1,5 +1,8 @@
+# pyright: reportUnusedImport=false
+import contextlib
 import logging
 
+import httpx
 from fastapi import FastAPI, Request, status
 from fastapi.encoders import jsonable_encoder
 from fastapi.exceptions import RequestValidationError
@@ -14,11 +17,26 @@
 import nominees.urls
 import officers.urls
 import permission.urls
+import translink.urls
 from constants import IS_PROD
 
 logging.basicConfig(level=logging.DEBUG)
 database.setup_database()
 
+
+@contextlib.asynccontextmanager
+async def lifespan(app: FastAPI):
+    """
+    Handles startup and shutdown events, see https://fastapi.tiangolo.com/advanced/events/
+    """
+    app.state.http_client = httpx.AsyncClient()
+    yield
+    await app.state.http_client.aclose()
+    if database.sessionmanager._engine is not None:
+        # Close the DB connection
+        await database.sessionmanager.close()
+
+
 # Enable OpenAPI docs only for local development
 if not IS_PROD:
     print("Running local environment")
@@ -27,7 +45,7 @@
         "http://localhost:8080",  # for existing applications/sites
     ]
     app = FastAPI(
-        lifespan=database.lifespan,
+        lifespan=lifespan,
         title="CSSS Site Backend",
         root_path="/api",
     )
@@ -41,7 +59,7 @@
         "https://madness.sfucsss.org",
     ]
     app = FastAPI(
-        lifespan=database.lifespan,
+        lifespan=lifespan,
         title="CSSS Site Backend",
         root_path="/api",
         docs_url=None,  # disables Swagger UI
@@ -60,6 +78,7 @@
 app.include_router(officers.urls.router)
 app.include_router(permission.urls.router)
 app.include_router(event.urls.router)
+app.include_router(translink.urls.router)
 
 
 @app.get("/")

src/nominees/urls.py

@@ -84,7 +84,7 @@ async def get_nominee_info(db_session: database.DBSession, computing_id: str):
     operation_id="delete_nominee",
     dependencies=[Depends(perm_election)],
 )
-async def delete_nominee_info(db_session: database.tDBSession, computing_id: str):
+async def delete_nominee_info(db_session: database.DBSession, computing_id: str):
     try:
         await nominees.crud.delete_nominee_info(db_session, computing_id)
         await db_session.commit()

src/translink/README.md

@@ -0,0 +1,16 @@
+# TransLink API Documentation
+This is supporting documentation for the TransLink API our server uses.
+This server only filters for the buses that begin/end at the upper bus loop at SFU Burnaby campus which are: 143, 144, 145, and R5.
+All dates are adjusted for the America/Vancouver timezone.
+
+## Quickstart
+1. You need an API key to do anything with realtime data. You can sign up for one [here](https://www.translink.ca/about-us/doing-business-with-translink/app-developer-resources/register
+2. Put the API key in `src/.env` with the key `TRANSLINK_API_KEY=<your API key>` or create an environment variable `export TRANSLINK_API_KEY=<your api key>`.
+3. Make sure your database has the correct migrations `alembic upgrade head`. Reload your test database as well `python src/load_test_db.py`
+4. Start (or restart) the web server to test the endpoints
+
+## Endpoints
+You can see the exact schemas in the `/docs` page. At the time this was written there are three endpoints:
+1. `translink/realtime`: returns realtime data for buses that are at or are approaching SFU
+2. `translink/static`: returns the schedule for the current day
+3. `translink/schedule`: combines the realtime and static data to show if a bus is at the loop, is running late, or was cancelled