Mobility Database API Client

A Python client for downloading GTFS files through the Mobility Database API.

Features

• Search for GTFS providers by country, name or id
• Download GTFS datasets from hosted or direct sources
• Track dataset metadata and changes
• Thread-safe and process-safe operations
• Automatic token refresh and error handling

Without an API token, the client uses MobilityData's current V2 CSV catalog. CSV searches support full feed IDs such as mdb-123, tld-5862, and tdg-81995; numeric IDs such as 123 also resolve to their mdb- feed. Inactive, deprecated, redirected, and non-GTFS feeds are excluded. The V2 catalog has a separate cache, so first use after upgrading requires an internet connection.

Installation

pip install mobility-db-api

Quick Example

from mobility_db_api import MobilityAPI

# Initialize client (uses MOBILITY_API_REFRESH_TOKEN env var)
api = MobilityAPI()

# Search for providers in Belgium
providers = api.get_providers_by_country("BE")
print(f"Found {len(providers)} providers")

# Download a dataset
if providers:
    dataset_path = api.download_latest_dataset(providers[0]['id'])
    print(f"Dataset downloaded to: {dataset_path}")

Documentation

Full documentation is available at bdamokos.github.io/mobility-db-api, including:

• Quick Start Guide
• Examples
• API Reference
• Contributing Guide

Development

# Clone repository
git clone https://github.com/bdamokos/mobility-db-api.git
cd mobility-db-api

# Install in development mode
pip install -e ".[dev]"

# Run tests
pytest

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Mobility Database for providing the API