GTFS Django

A Django package that provides abstract models for GTFS (General Transit Feed Specification) data, covering both static Schedule feeds and dynamic Realtime feed messages.

Because all models are abstract, this package creates no database tables of its own. You subclass the models in your own Django app, giving you full control over your schema — adding foreign keys, extra fields, constraints, or any other customisations your project requires.

The package gtfs-django also includes custom Django model fields that handle GTFS-specific data types and formats, such as time fields that support hours greater than 24, geographic coordinate fields, and validated fields for color codes, language tags, and more.

Finally, gtfs-django provides utilities for importing GTFS data from ZIP files, parsing GTFS Realtime protobuf messages, and validating GTFS feed contents against the specification.

Requirements

• Python: 3.12+
• Django: 5.2+

Installation

pip install gtfs-django

uv add gtfs-django

Quick Start

1. Add to your Django settings

INSTALLED_APPS = [
    # ...
    "gtfs",
]

2. Subclass the abstract models in your app

Add auxiliary tables or new fields as needed.

from django.db import models
from gtfs.models import BaseAgency, BaseRoute, BaseTrip, BaseStop, BaseStopTime


class Feed(models.Model):
    """Represents a versioned GTFS feed download."""
    name = models.CharField(max_length=255)
    downloaded_at = models.DateTimeField(auto_now_add=True)


class Agency(BaseAgency):
    feed = models.ForeignKey(Feed, on_delete=models.CASCADE)


class Route(BaseRoute):
    feed = models.ForeignKey(Feed, on_delete=models.CASCADE)
    agency = models.ForeignKey(Agency, on_delete=models.CASCADE)


class Trip(BaseTrip):
    feed = models.ForeignKey(Feed, on_delete=models.CASCADE)


class Stop(BaseStop):
    feed = models.ForeignKey(Feed, on_delete=models.CASCADE)


class StopTime(BaseStopTime):
    feed = models.ForeignKey(Feed, on_delete=models.CASCADE)

3. Run migrations for your app

python manage.py makemigrations <your_app_name>
python manage.py migrate

Abstract Models

GTFS Schedule

GTFS Realtime

Custom Fields

gtfs.fields provides Django model fields that encode GTFS type semantics:

Development

git clone https://github.com/simovilab/gtfs-django.git
cd gtfs-django

# Install with development dependencies
uv sync

# Run tests
pytest

Regenerating Schedule models

gtfs/builder/schedule.yaml is the source of truth for the GTFS Schedule models. After changing it or gtfs/builder/mappings.py, generate gtfs/builder/models.py from the repository root:

uv run python -m gtfs.builder.builder

The generated file contains Schedule models only. Review and migrate its contents into gtfs/models.py manually; the generator does not modify that file.

Contributing

Contributions are welcome. For major changes please open an issue first.

1. Follow Django coding standards
2. Add tests for new features
3. Update documentation as needed
4. Ensure compatibility with Django 5.2+

License

Apache License 2.0 — see LICENSE for details.

Credits

Developed by SIMOVI Lab.

For more information about GTFS, visit gtfs.org.