gobble

Gobble is a service that reads the MBTA V3 Streaming API for all train/bus events, and writes them out to a format that can be understood by the TransitMatters Data Dashboard.

Requirements to develop locally

• uv with Python 3.14
  • With mise installed, mise trust && mise install sets up Python (pinned in .python-version)

Development Instructions

1. Duplicate config/template.json into config/local.json, and change the null out with your MBTA V3 API key.
2. In the root directory, run uv sync --group dev to install dependencies followed by uv run pre-commit install to install pre-commit hooks
3. Run uv run src/gobble.py to start.
4. Output will be in data/ in your current working directory. Good luck!

GTFS archives are downloaded to data/gtfs_archives/ by default. Set GTFS_DATA_DIR to share them with other TransitMatters repos (they'll go in $GTFS_DATA_DIR/gtfs_archives). Note that gobble prunes archives older than gtfs.archive_retention_days, which also applies to a shared directory.

Container

You can also run Gobble inside a container using the following docker build and docker run commands

docker build -t gobble -f Containerfile .
docker run \
    -v ./config/local.json:/app/config/local.json:z \
    -v ./data:/app/data:z \
    gobble:latest

Output will be in data/ in your current working directory. Good luck!

Linting

You can run the linter against any code changes with the following commands

$ uv run ruff check --fix src
$ uv run ruff format src

Testing

Tests live in src/tests/ and need a config/local.json (a copy of config/template.json is enough). Run them with

$ uv run pytest

Support TransitMatters

If you've found this app helpful or interesting, please consider donating to TransitMatters to help support our mission to provide data-driven advocacy for a more reliable, sustainable, and equitable transit system in Metropolitan Boston.