gotime

gotime is a multi-provider driving-directions library with a Typer CLI and SQL persistence. This site documents the architecture, schema, provider coverage, pricing / free-tier strategy, compliance posture for persisting raw responses, and release engineering.

Contents

• Architecture
  • Layers
  • Verifying keys
  • Configuration
• Database schema
  • Entity-relationship diagram
  • Tables
  • Provider capability matrix
• Storage & persistence
  • Choosing a backend
  • Retention & cost
• Compliance: persisting provider responses
  • Default behaviour
  • Per-provider summary
  • If you opt in
  • Related
• Pricing & free-tier strategy (USA)
  • Google Maps Platform
  • Bing Maps
  • TomTom
  • HERE
  • MapQuest
  • Mapbox
  • Azure Maps
  • Multi-provider budget sheet
• Versioning policy
  • Why CalVer + SemVer?
  • How versions are computed (no manual edits)
  • Pre-releases
  • Dealing with broken releases
  • Supported Python versions
  • Procedure
• Release runbook
  • Goals
  • One-time maintainer setup
  • Normal release
  • Backport / hotfix flow
  • Pre-release flow
  • Failure playbook
  • Who can release?
  • Cross-references
• Development roadmap
  • Short term
  • Tier 2 provider integrations
  • Longer term
• Provider reference
  • Google Maps Directions
  • Bing Maps Routes
  • TomTom Routing
  • HERE Routing v8
  • MapQuest Directions
  • Mapbox Directions (driving-traffic)
  • Azure Maps Route

Legacy data migration

Older iterations of the project produced SQLite databases, Postgres dumps, and CSV exports. The turnkey Docker pipeline for consolidating those into a fresh gotime schema lives outside the PyPI package, in the workspace at scripts/merge/README.md. That directory is deliberately not shipped with the library — operators who need it should grab it from the gotime repository.

At a glance

• Tier-1 providers: Google, Bing, TomTom, HERE, MapQuest, Mapbox, Azure.

• Normalized TripResult with typed units (seconds, meters, plus helpers).

• SQLAlchemy 2.x schema with Alembic migrations (SQLite + Postgres).

• Black (120-col) + Ruff + mypy + pytest-cov ≥ 90 %.

• Dockerized integration tests and CI via GitHub Actions.

Install

pip install gotime

Quick CLI tour

gotime providers list
gotime db info
gotime query \
  --origin 42.3554,-71.0654 \
  --destination 42.3467,-71.0972 \
  --provider google --provider tomtom --json