GTFS Django Development Environment

A Django development environment for testing and developing the gtfs-django package - a comprehensive Django application for processing and managing GTFS (General Transit Feed Specification) data.

🚀 Quick Start

Prerequisites

• Python 3.12+
• PostgreSQL with PostGIS extension
• UV package manager (required)

Installation

1. Clone and setup:

   git clone <repository-url>
   cd gtfs-django-dev
   uv sync

2. Configure environment:

   cp .env.example .env
   # Edit .env with your database credentials

3. Setup database:

   createdb -O your_user your_database_name
   psql your_database_name -c "CREATE EXTENSION postgis;"
   uv run python manage.py migrate

4. Create superuser and run:

   uv run python manage.py createsuperuser
   uv run python manage.py runserver

🎯 Purpose

This development environment serves as:

• Testing Ground: Safe environment to test GTFS data processing and real-time feeds
• Development Platform: Editable installation of gtfs-django package for active development
• Learning Environment: Complete setup with sample data to understand GTFS concepts
• Integration Testing: Test GeoDjango spatial queries and PostGIS functionality

📊 Features

GTFS Data Support

• ✅ Static GTFS: Agencies, routes, trips, stops, schedules, calendars
• ✅ Real-time GTFS: Trip updates, vehicle positions, service alerts
• ✅ Geographic Data: PostGIS integration for spatial queries
• ✅ Multi-provider: Support for multiple transit agencies

Development Tools

• 🔧 Django Admin: Built-in interface for data management
• 🗺️ GeoDjango: Spatial database operations and geographic queries
• 📦 Sample Data: Pre-loaded fixtures for testing
• 🔄 Live Reloading: Editable package installation

📁 Project Structure

gtfs-django-dev/
├── dev/                    # Django project settings
│   ├── settings.py        # Configuration with PostGIS
│   ├── urls.py           # URL routing
│   └── wsgi.py           # WSGI configuration
├── manage.py              # Django management script
├── pyproject.toml         # Dependencies and metadata
├── uv.lock               # Locked dependencies
├── WARP.md               # Detailed documentation
└── README.md             # This file

💡 Usage Examples

Load Sample Data

uv run python manage.py loaddata example

Django Shell Examples

# Start Django shell
uv run python manage.py shell

# Import models
from gtfs.models import GTFSProvider, Route, Stop
from django.contrib.gis.geos import Point
from django.contrib.gis.measure import Distance

# Create a transit provider
provider = GTFSProvider.objects.create(
    code='metro',
    name='Metropolitan Transit',
    timezone='America/New_York',
    is_active=True
)

# Find nearby stops (requires PostGIS)
center = Point(-84.0491, 9.9355)
nearby_stops = Stop.objects.filter(
    stop_point__distance_lte=(center, Distance(km=1))
)

Admin Interface

Access the Django admin at http://localhost:8000/admin/ to manage GTFS data through a web interface.

🔗 Related Projects

• gtfs-django: The main GTFS Django package being developed
• GTFS Reference: Official GTFS specification
• GTFS Realtime: Real-time transit information standard

📚 Documentation

For detailed setup instructions, architecture overview, and advanced usage, see WARP.md.

🛠️ Development

This project uses an editable installation of the gtfs-django package. Any changes to the package in ../gtfs-django are immediately reflected in this development environment.

Common Commands

# Run development server
uv run python manage.py runserver

# Django shell
uv run python manage.py shell

# Database migrations
uv run python manage.py migrate

# Load test data
uv run python manage.py loaddata example

# Access database directly
uv run python manage.py dbshell

🌍 GeoDjango Features

This development environment showcases GeoDjango capabilities:

• Spatial Queries: Find stops within distance, route intersections
• Geographic Data Types: Points for stops, LineStrings for route shapes
• PostGIS Integration: Advanced spatial operations and indexing
• Real-world Coordinates: Sample data with actual geographic coordinates

---

Note: This is a development environment. For production deployment of GTFS applications, refer to the main gtfs-django package documentation.