Repository navigation
Principles
These are the promises the ViaFrei API makes. Each one is backed by a concrete design mechanism and, where possible, by an automated test that fails if the promise is broken.
ViaFrei's data comes from many publishers under different licences: open licences that require attribution, share-alike licences, and terms that restrict use to consumer information or require explicit acceptance.
| Promise | How it is kept |
|---|---|
| Every answer says who published the data and under which licence | A meta.attribution block in every data response, plus a Link: …; rel="license" header pointing to the public source register |
| Condition and purpose notes are passed on word for word |
meta.notes.condition and meta.notes.purpose carry the licence's required sentences verbatim |
| A key never receives data its plan may not receive | The licence gate decides, per request, which source families a key may read; the allowed set is passed into the database query, so forbidden rows are never read |
| Defence in depth | Every returned row is checked again against the allowed set; a violation is an error and an alert, never a silent leak |
| Default deny | A source family is enabled for a plan only after its licence has been reviewed; until then the gate refuses it |
| Share-alike data stays share-alike | Such answers carry their condition note and a pointer to the corresponding share-alike export |
The public source register is available at GET /v1/sources. See Security and Access Keys for how plans and use classes interact with the gate.
- The API serves mobility data, not personal data.
- API keys are never stored in plain text and never written to logs. Logs carry only the public key id.
- Client IP addresses in logs are truncated to a network prefix.
- Keys in URLs are refused (
400 key-in-query), because URLs end up in logs and browser histories. - Usage metering records counts per key, hour and feature, not request contents.
- Hosting is in Germany, and no third-party key-management or gateway service holds key-holder data.
- Read-only database access through a dedicated role that cannot write and cannot see beyond the read contract (tested).
- Keys with high entropy, a checksum, a visible prefix for secret scanning, expiry, rotation with an overlap window, and immediate revocation.
- Strict input validation and size limits on every parameter; bounded areas, windows and page sizes.
- Signed, scanned container images with provenance and an SBOM; dependency scanning on every pull request.
- Private vulnerability reporting on the repository.
Details: Security and Access Keys and Development Process.
- Hard deadline: no request runs longer than 2 seconds. The budget starts when the request arrives; queueing spends from it.
- The database stops too: when a request's time is up, its query is cancelled inside PostgreSQL, not merely abandoned by the client.
-
Fail fast: if a request cannot be served in time, it is refused at once with a clear error and a
Retry-Afterhint, instead of waiting and failing late. -
Partial answers are honest: a composed answer (for example a route briefing) reports the status of each part (
ok,timeout,not_permitted,unavailable) instead of failing completely. - Good neighbour: the API has a hard cap on its share of the shared database, so it can never starve the MCP server or the website.
Details: Rate Limits and Priority.
- This design is public before the code.
- The OpenAPI 3.1 document is generated from the code, committed, linted and diffed for breaking changes on every pull request.
- Every documented example is executed against test fixtures in CI, so the documentation cannot drift from behaviour.
-
GET /v1/metareports the API version, the platform version and the read-contract version it was built against. - Every configuration key is documented with its default and bounds, generated from the code.
Public pull requests, required reviews, public CI, CodeQL, dependency review, OpenSSF Scorecard, automated releases with changelogs, and published documentation. See Development Process.
We label design targets as targets and assumptions as assumptions. We do not publish numbers we have not measured on the thing being described.
Every behaviour is one national rule applied the same way everywhere. There are no special cases for one city or one region in the API's logic.
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