🚌 Open Bus Stride API

An API for the Open Bus Stride Project

📢 Get Involved

• 💬 For general help and system updates, join the Hasadna Slack: #open-bus channel
• 🐞 Found a bug or have a feature request? Open an issue
• 🤝 Want to contribute? See our contributing guidelines

🔗 Related Projects

Frontend

• 🗺️ Open Bus Map Search (Client App) - Live Website
• 📦 Open Bus API Client (API Package Generator) - NPM Package

Backend

• 🏗️ Open Bus Pipelines
• 🌐 Open Bus Stride API (REST) – API Docs
• 🧾 Open Bus Stride DB
• 🔧 Open Bus Stride ETL
• 📚 Open Bus GTFS ETL
• 📡 Open Bus SIRI Requester
• 🧪 Open Bus SIRI ETL

🛠️ Tech Stack

• Python
• FastAPI
• PostgreSQL

🚀 Getting Started

Option 1: Using Docker Compose (Recommended)

The easiest way to get up and running is with Docker Compose.
Follow the instructions here.

For local development (e.g. making changes to the code), also see:
Develop stride-api from a local clone in the same document.

Option 2: Local Development (Manual Setup)

Use this if you prefer to run directly from your local Python environment.

1. Clone and Setup

Ensure you have Python 3.8 installed.

Ensure a local clone of open-bus-stride-db exists at:

../open-bus-stride-db

requirements-dev.txt installs it as an editable dependency, so it must already be cloned before the next step.

python3.8 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install --upgrade pip
pip install -r requirements-dev.txt

2. Database Connection

You’ll need a database. You have two options:

• Option A: Start stride-db using the Docker Compose environment from open-bus-pipelines.
• Option B: Connect to the production DB using Redash read-only credentials.

Create a .env file:

export SQLALCHEMY_URL=postgresql://postgres:123456@localhost

Then source it:

. .env

3. Run the API Server

uvicorn open_bus_stride_api.main:app --reload

This is for local development (--reload picks up code changes). In Docker/production the app is served via gunicorn with a uvicorn worker class instead - see the ENTRYPOINT in Dockerfile and gunicorn_conf.py.

Access the interactive API docs at: 👉 http://localhost:8000/docs

🧩 API Development

All routes are defined in:

open_bus_stride_api/routers/<base_router_name>.py

✍️ Example API

@router.<http_method>("/<api_path>", tags=["<tag_name>"], response_model=<ResponseModel>)
def name(<filtering_params>, limit, offset):
    return common.get_list(
        <DBModel>, limit, offset,
        [
            {'type': <filter_type>, 'field': <DBModel>.<field>, 'value': <filter_param>},
        ]
    )

• Filters: Defined in routers/common.py → get_list_query_filter_<filter_type> (Examples: 'equal', 'date_in_range')

Always include limit and offset for pagination.

🧪 Running Tests

Set up your environment as described in the Local Development section above.

Install test dependencies:

pip install -r tests/requirements.txt

Ensure the DB contains full Stride data (production read-only access works).

Run tests:

pytest -svvx