Version 0.2.1
Live German mobility data, through one clean REST interface.
The German Real-Time Mobility Context Platform for AI
Website · Wiki · Roadmap · MCP server
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.
429 and Retry-After instead of making you wait.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.
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.
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.
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.
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
The wiki holds the full design:
Technical specification (index), with numbered requirements traced in the Traceability Matrix:
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.
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.
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.