Repository navigation
Vision and Goals
This page explains why the ViaFrei API exists, who it is for, what it promises, and what is deliberately outside its scope.
Germany publishes a great deal of open mobility data: motorway traffic and roadworks, fuel prices, charging points, parking, timetables and real-time public transport, station facilities, official weather warnings and reference data about places. It is spread across many publishers, formats, licences and update rhythms. Anyone who wants a single, consistent answer such as "what should I know before I drive the A8 west this afternoon?" has to integrate all of it, keep it running and respect every licence on the way.
ViaFrei does that integration once and keeps it current. Today it serves the result to AI assistants through its MCP server. The API serves the same result to everyone else.
One trustworthy, documented and stable interface to live German mobility context, where every answer says where it comes from and under which terms it may be used.
| Audience | What they need from the API |
|---|---|
| Application developers | Simple REST calls, clear documentation, examples that work, predictable errors |
| Fleet, logistics and mobility businesses | Conditions along corridors, energy and parking stops, history windows, priority under load, stable versions |
| AI and agent builders who prefer plain HTTP | The same facts the MCP server gives, as JSON or GeoJSON |
| Researchers and public-interest projects | Licence-clean access with explicit attribution |
- Feature-first. Endpoints answer questions people ask ("conditions along this motorway", "where to charge along my route"), not tables. See Domain Model.
- Licence-correct by construction. A key only ever receives data its plan and use class are allowed to receive, and every answer carries the attribution its licence requires. See Principles.
- Fast and bounded. No request runs longer than a hard 2 second deadline, and most endpoints target well under that (design targets on Performance and Caching).
- Fair under load. Priority tiers protect critical callers, and the API can never starve the shared data platform. See Rate Limits and Priority.
- Parity with the MCP server. For the same input, an endpoint answers the same facts as the matching MCP capability.
- Stable. Versioned paths, additive changes within a version, announced deprecations. See API Design.
- Open process. Public repository, public CI, public security scanning, public releases. See Development Process.
- The API does not describe or expose how data is collected. It is about access to data that already exists. The repository, the documentation and the responses contain nothing about collection: no internal names, no source endpoints, no collection schedules. A response names a source only as its attribution requires.
- No write access. The API is read-only. It never changes ViaFrei's data.
- No generic query language. There is no "filter any column" interface and no GraphQL. Open-ended queries are a risk to a shared database and say nothing about the domain.
- No routing engine. The API reports conditions along roads and routes; it does not compute routes.
- No real-time push in v1. Webhooks or server-sent events for watched situations come later, with their own design.
flowchart LR
subgraph Platform[ViaFrei platform]
DB[(Shared database)]
RC[Read contract<br/>published views]
DB --> RC
end
RC --> MCP[MCP server<br/>for AI assistants]
RC --> API[viafrei-api<br/>REST for developers]
RC --> WEB[viafrei.de]
The API reads only the read contract: a published, versioned set of views maintained by the platform. It never touches the platform's internal storage, so the platform can evolve its storage freely and the API's clients never notice. See Architecture Overview.
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