Version 0.2.1

ViaFrei API

Live German mobility data, through one clean REST interface.

The German Real-Time Mobility Context Platform for AI

Website · Wiki · Roadmap · MCP server

status api openapi


What it is

ViaFrei API gives applications keyed, read-only access to live mobility information for Germany:

Domain What you can ask
Roads Conditions along a motorway or a route, closures, roadworks ahead
Energy Where to refuel or charge near a place or along a route, with current prices and availability
Parking Car and lorry parking near a place, with occupancy where it is published
Public transport Departures and disruptions at a stop or station
Accessibility Lifts and escalators at stations, in service or not
Weather risk Official weather warnings for a place or along a route
Places Search and resolve places and addresses across Germany

ViaFrei already serves this data to AI assistants through its MCP server. The API makes the same facts available to any software, through stable, documented HTTP endpoints.

Design principles

Planned API

GET /v1/route-briefing?from=Hamburg&to=Hannover
Authorization: Bearer <your key>
{
  "route": { "from": "Hamburg", "to": "Hannover" },
  "roads": { "closures": [ ... ], "roadworks": [ ... ] },
  "energy": { "fuel": [ ... ], "charging": [ ... ] },
  "weather": { "warnings": [ ... ] },
  "attribution": [ { "publisher": "...", "licence": "..." } ]
}

Illustrative only: the v1 endpoint list is being designed in the open. See API Design.

Standards we build on: OpenAPI 3.1, RFC 9457 problem details for errors, cursor pagination, GeoJSON for geometry, ETag caching.

Status

ViaFrei API has a service skeleton in Go. Nothing is deployed yet, and no data endpoint exists.

Step State
Goals, principles and domain model ✅ Written
Technology evaluation ✅ Published in the wiki
Technical specification 📝 Draft for review, revision 1 — published in the wiki: protocol, requests and responses, errors, keys, limits, non-functional requirements
Logical data model 📝 Draft — Data Model: entities, fields and diagrams per domain, mapped to API fields (never a copy of storage)
Testing strategy and test plans 📝 Draft — Testing Strategy; unit, handler and integration tests run, 100 % statement coverage per package is enforced (coverage); test infrastructure continues in #14–#20
Synthetic fixture generator 🔄 In review — seeded, Germany-wide, fictional (docs/test-data.md)
Architecture for Go, Rust and TypeScript ✅ Stack Comparison
Stack decision ✅ Go — ADR-0001 accepted on 2026-11-01
Configuration layer ✅ Every tunable is a documented key with bounds — docs/configuration.md
Service skeleton: /healthz, /readyz, /v1/meta, /v1/openapi.json 🔄 In review (milestone 0.2.0)
Container image (distroless, multi-arch) and local Compose stack 🔄 In review — docs/container.md
CI, security checks and release pipeline 🔄 In review — CI on every pull request; SAST, secrets, dependency, licence and DAST checks (docs/security-checks.md); release-please, signed images and release pages (docs/RELEASING.md)
Keys, rate limits and priority tiers ⏳ Planned
v1 feature endpoints ⏳ Planned

Follow progress in the Roadmap and in Issues.

Build and run

Requirements: Go 1.27 (the exact toolchain is pinned in go.mod), and a container runtime for the integration tests.

make build              # bin/viafrei-api, static, version and commit stamped in
make test               # unit and handler tests
make test-integration   # adds tests against a throwaway PostGIS container
make coverage           # unit + integration + boot profiles, 100 % per package or it fails
make generate           # regenerate sqlc code, docs/configuration.md, api/openapi.json
make fixtures PROFILE=ci SEED=7   # synthetic test data, see docs/test-data.md

The service reads its configuration from environment variables with the prefix VFAPI_ and, optionally, a YAML file named by VFAPI_CONFIG_FILE. Every key, its default and its bounds are listed in docs/configuration.md. An unknown key or a value out of bounds stops the service at start-up with exit status 78. The one required value is the database URL of the service's read-only role:

export VFAPI_DB_URL_FILE=/run/secrets/db_url   # or VFAPI_DB_URL=postgres://...
bin/viafrei-api config check                    # validate and exit
bin/viafrei-api                                 # serve on localhost:8080
curl -s localhost:8080/healthz                  # {"status":"ok"}
curl -s localhost:8080/v1/meta                  # API, build and read-contract versions

Other subcommands: healthcheck (exit 0 when /healthz answers, for container healthchecks), config show (effective values, secrets hidden), config docs, openapi, version.

The database the service reads is described by a versioned read contract in db/contract/: logical names only, created with a read-only role. Tests build it in a throwaway container. They never reach a live data source or production.

Run with Docker

The image is distroless, runs as non-root and is built for linux/amd64 and linux/arm64. Releases and main are published to ghcr.io/mavrovde/viafrei-api, signed with cosign, and carry an SBOM and build provenance.

docker run --rm --read-only -p "[::1]:8080:8080" \
  -e VFAPI_DB_URL_FILE=/run/secrets/db_url -v "$PWD/db_url:/run/secrets/db_url:ro" \
  ghcr.io/mavrovde/viafrei-api:edge

docs/container.md covers the tags, the healthcheck subcommand, resource limits and how to verify an image's signature, SBOM and provenance before running it.

Local development with Compose

compose.yaml starts the API and a PostGIS database that holds the read-contract stub, the read-only role and a synthetic fixture set. Only the API is published, and only on the loopback interface.

cp .env.example .env    # replace both placeholders
make up                 # build, start, wait until healthy
curl -s localhost:8080/v1/meta
make compose-test       # smoke test with Schemathesis, then teardown
make down               # or: make reset to drop the database volume

Documentation

The wiki holds the full design:

Technical specification (index), with numbered requirements traced in the Traceability Matrix:

Releases

Releases are cut by release-please from Conventional Commits: merging the release pull request tags vX.Y.Z (annotated) and publishes the release page with the signed multi-arch image ghcr.io/mavrovde/viafrei-api:X.Y.Z, its SBOM and provenance, openapi.json with its diff against the previous release, and checksums. Every 0.x release is a pre-release. The CHANGELOG lists the changes; docs/RELEASING.md is the maintainer checklist, including rollback, hotfixes and yanking.

Security

Please do not report security issues in public issues. Use GitHub's private vulnerability reporting. See SECURITY.md for response times; the automated checks are listed in docs/security-checks.md.

Contributing

Ideas and questions are welcome in Issues. Code contributions are welcome through pull requests; the process (pull requests, required checks, review) is described in Development Process.

Related


ViaFrei is in beta. Sources are still being added, and coverage can change.