Skip to content

Vision and Goals

mavrovde edited this page Nov 1, 2026 · 1 revision

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.

The problem

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.

The vision

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.

Who it is for

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

Goals

  1. Feature-first. Endpoints answer questions people ask ("conditions along this motorway", "where to charge along my route"), not tables. See Domain Model.
  2. 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.
  3. 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).
  4. Fair under load. Priority tiers protect critical callers, and the API can never starve the shared data platform. See Rate Limits and Priority.
  5. Parity with the MCP server. For the same input, an endpoint answers the same facts as the matching MCP capability.
  6. Stable. Versioned paths, additive changes within a version, announced deprecations. See API Design.
  7. Open process. Public repository, public CI, public security scanning, public releases. See Development Process.

Non-goals

  • 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.

Relation to the ViaFrei platform

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]
Loading

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.

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally