Repository navigation
Home
viafrei-api is the planned public, RESTful, keyed and read-only HTTP API to ViaFrei's live German mobility data. ViaFrei describes itself as The German Real-Time Mobility Context Platform for AI: it brings motorway traffic, roadworks, fuel prices, EV charging, parking, public-transport departures and disruptions, station accessibility, weather warnings and places into one consistent, Germany-wide picture.
ViaFrei already serves that picture to AI assistants through its MCP server (see viafrei.de). The API is the second door to the same data: a conventional, documented REST interface for developers, applications and businesses that want structured answers instead of a conversation.
Status: design phase. Nothing is implemented yet. The architecture, principles and endpoint plan on these pages are published before the code, so anyone can see what we intend to build and hold us to it. The implementation language is still open: Go and Rust are the preferred candidates and TypeScript is compared in full as the third; a benchmark decides. See Project Status.
| Domain | Typical question the API answers |
|---|---|
| Road conditions | How is the A8 between Munich and Stuttgart right now? What roadworks are ahead of me? |
| Energy stops | Where can I refuel or charge near a place or along my route? |
| Parking | Where can I park a car or a lorry near X or along the route? |
| Public transport | What are the next departures at a station, and what is disrupted there? |
| Accessibility | Are the lifts and escalators at this station working? |
| Weather risk | Are there official weather warnings at a place or along a route? |
| Places | Where is X, and what is around it? |
| Driving rules | What are the curated rules for, for example, lorries on Sundays? |
Every answer names the publisher and licence of the data it contains. See Principles.
- Vision and Goals: why the API exists, who it is for, and what it will never do.
- Principles: the promises we make about licences, privacy, security, reliability and openness.
- API Design: the feature-first endpoint plan, errors, pagination, GeoJSON, versioning and attribution.
- Technical Specification: the normative, numbered requirements of the API, from protocol and envelope to operations, with a traceability matrix.
- Architecture Overview: how a request flows, and how the API stays independent of the platform's storage.
- Data Model: the logical read model behind every answer, with diagrams, field tables, the mapping to the API and a data dictionary.
- Testing Strategy: how the API will be tested, from unit tests to release acceptance, with a test plan per milestone. Tests never touch a live data source or production.
- Technology Evaluation: every technology we considered, with a verdict and a reason.
- Stack Comparison (Go, Rust and TypeScript) and Benchmark Plan: the open stack decision and how it will be made. The three designs: Architecture: Go, Architecture: Rust, Architecture: TypeScript.
- Roadmap: the phases, mapped to features. No dates are promised.
- FAQ and Glossary.
The repository is public and developed in the open: pull requests, CI, security scanning and releases are all visible. See Contributing for how to follow progress, report a problem or propose a change.
On these pages, design target means a goal the implementation must meet and that tests will check. Assumption marks something we believe but have not yet confirmed. Nothing on these pages is a measurement of a running ViaFrei API, because there is no running API yet.
ViaFrei API: a public, keyed, read-only REST API to live German mobility data. Design phase; nothing on these pages is a measurement of a running service. Data on viafrei.de and in every API answer is attributed to its publishers under their licences.
About
Design
- Domain Model
- API Design
- Architecture Overview
- Security and Access Keys
- Rate Limits and Priority
- Performance and Caching
- Configuration
- Observability
Data Model
Technical specification
-
Technical Specification
- Interface
- Scope, Conventions and References
- Protocol
- Common Envelope
- Resource Model
- Endpoints, Places
- Endpoints, Roads
- Endpoints, Energy and Parking
- Endpoints, Public Transport and Accessibility
- Endpoints, Weather Risk, Driving Rules and Composed Features
- Service Endpoints
- Errors
- Authentication and Authorisation
- Rate Limiting, Quotas and Priority
- Data Licensing and Attribution
- Compatibility and Versioning
- OpenAPI Skeleton
- Quality
- Delivery and operations
- Interface
Testing
- Testing Strategy
- Testing and Quality (design summary)
Engineering
Technology choice
- Technology Evaluation
- Architecture: Go
- Architecture: Rust
- Architecture: TypeScript
- Stack Comparison
- Benchmark Plan
Reference