Repository navigation
API Design
This page is the public contract we intend to implement: the feature-first endpoint plan, the response shape, errors, pagination, GeoJSON, attribution and versioning. It is a plan; the final list is reviewed before implementation and published as an OpenAPI 3.1 document. The normative, numbered requirements are in the Technical Specification, which takes precedence where the two differ.
| Topic | Rule |
|---|---|
| Base path | /v1 |
| Authentication |
Authorization: Bearer <key> or X-API-Key: <key>; never in the URL |
| Formats |
application/json by default; application/geo+json on request; errors as application/problem+json
|
| Field names | English, camelCase. Enum values are snake_case strings. Ids are opaque and prefixed (for example pl_…, rs_…, sp_…) |
| Language | The lang parameter, else Accept-Language, selects the language of texts (default de); Content-Language reports it ([[Spec: Protocol |
| Time | ISO 8601 instants in UTC with Z; where people read them, a …Local companion in Europe/Berlin with its offset ([[Spec: Scope, Conventions and References |
| Unknown fields | Clients must ignore fields they do not know; new fields can appear within v1 |
Any feature that needs a location accepts one of:
-
at=lat,lon: a coordinate; -
place=<id>: a place id from the places search; -
q=<text>: a free-text place. An ambiguous text returns422 ambiguous-placewith the candidates (Spec: Errors, ADR-0003).
"Along" features accept a motorway section (road=…&direction=…&from=…&to=…) or a client route (route=<encoded polyline>; long routes can use POST with the same fields in the body; POST is offered on these long-route operations only, as a safe query, ADR-0005).
| Feature | Path | Answer | Scope |
|---|---|---|---|
| Place search | GET /v1/places?q=&near=&kind= |
Place[] |
places |
| Place overview (composed) | GET /v1/places/{id}/overview?needs= |
a lamp and the top items per need, with part statuses | per part |
| Describe a point | GET /v1/locations/describe?at= |
place, federal state, district, nearest junction | places |
| Addresses | GET /v1/addresses?q= |
Address[] |
places |
| Points of interest | GET /v1/points-of-interest?near…&category= |
PointOfInterest[] |
places |
| Motorways | GET /v1/motorways |
road, name, lamp, number of situations | roads |
| Motorway conditions | GET /v1/motorways/{road}/conditions?direction=&from=&to= |
Corridor, lamp, RoadSituation[]
|
roads |
| Roadworks ahead | GET /v1/motorways/{road}/roadworks-ahead?at=&direction=&within_km= |
situations ordered by distance ahead | roads |
| Conditions in an area | GET /v1/road-conditions?near…&kinds= |
situations and an area lamp | roads |
| Condition history | GET /v1/motorways/{road}/conditions/history?from=&to=&cursor= |
a page of observations | roads + history |
| Route briefing (composed) |
GET /v1/route-briefing?…&needs= or POST
|
Briefing |
per part |
| Refuel | GET /v1/refuel-options?near…|along…&product=&sort=price|distance |
FuelStop[], hydrogen included |
energy |
| Charging | GET /v1/charging-options?near…|along…&min_kw=&connector=&available_now= |
ChargingSite[] |
energy |
| Parking | GET /v1/parking-options?near…|along…&vehicle=car|lorry |
ParkingSite[] |
parking |
| Car sharing | GET /v1/sharing-options?near… |
SharingStation[] |
parking |
| Stop search | GET /v1/stop-places?q=&near= |
StopPlace[] |
transit |
| Departures | GET /v1/stop-places/{id}/departures?modes=&from= |
Departure[] |
transit |
| Disruptions |
GET /v1/stop-places/{id}/disruptions, GET /v1/disruptions?near…
|
Disruption[] |
transit |
| Accessibility | GET /v1/stop-places/{id}/accessibility |
StationAccessibility |
accessibility |
| Weather risk | GET /v1/weather-risk?near…|along… |
WeatherRisk |
weather |
| Driving rules | GET /v1/driving-rules?topic=&vehicle= |
RuleTopic |
rules |
| Sources | GET /v1/sources |
the public attribution and terms register | public |
| Meta and operations |
GET /v1/meta, /healthz, /readyz, /openapi.json, /docs
|
versions, health, the API description | public |
Each feature that has a counterpart in the MCP server answers the same facts for the same input; this is tested (see Testing and Quality). Condition history is API-only. Watching a situation over time is not part of v1; it will come later as webhooks or server-sent events, with its own design.
{
"data": {
"corridor": {"road": "A8", "direction": "west", "fromKm": 0, "toKm": 230},
"lamp": "amber",
"situations": [{
"id": "rs_…",
"kind": "roadworks",
"severity": "lane_closed",
"position": {"fromKm": 112.4, "toKm": 115.0, "junction": "Ulm-West"},
"validity": {"from": "2026-11-01T05:00:00Z", "fromLocal": "2026-11-01T06:00:00+01:00", "until": "2026-11-14T17:00:00Z", "untilLocal": "2026-11-14T18:00:00+01:00"},
"headline": "…",
"geometry": {"type": "LineString", "coordinates": ["…"]}
}]
},
"meta": {
"asOf": "2026-11-01T13:05:00Z",
"attribution": [{"family": "roads", "text": "…", "licence": "…", "licenceUrl": "…"}],
"notes": {"condition": [{"family": "roads", "text": "…verbatim…", "lang": "de"}], "purpose": []},
"page": {"limit": 50, "hasMore": true, "nextCursor": "eyJ2…"},
"requestId": "01JC…"
},
"links": {"self": "…", "next": "…"}
}The example is illustrative; values are placeholders. The full envelope is specified in Spec: Common Envelope.
-
Every data response carries
meta.attribution: one entry per source family that contributed, with the publisher's attribution text, the licence and a licence URL. - Condition and purpose notes required by a licence are carried verbatim in
meta.notes. They are legal conditions of the data, not captions, and clients displaying the data must show them. - A
Link: <…/v1/sources#family>; rel="license"header points to the public register. -
GET /v1/sourceslists every source family with its attribution, licence and conditions.
-
Accept: application/geo+jsonreturns an RFC 7946FeatureCollection. Themetablock is included as a foreign member, so attribution travels with the geometry. -
geometry=none|point|simplified|fullcontrols geometry detail; coordinates use six decimal places. - Geometry is built in the database, so large shapes cost no application CPU.
-
Keyset (cursor) pagination only.
OFFSETis never used. - The cursor is opaque and signed. It binds the position, the time window and a hash of the filters, and it expires. Replaying it with other filters or after expiry returns
400 invalid-cursor. - Default page size 50; the maximum depends on the plan and is capped by configuration.
-
History endpoints require a bounded time window (
fromandto). A missing window is400 window-required; a window larger than allowed is400 window-too-large. This keeps every history query on a small, indexed slice of data.
-
fields=selects a subset of fields, validated against the response schema. - gzip and brotli compression above a minimum size; zstd optional.
Every error is application/problem+json:
{
"type": "https://api.viafrei.de/problems/overloaded",
"title": "Service is busy",
"status": 429,
"detail": "The bulk tier is at capacity. Retry after 2 seconds.",
"instance": "/v1/route-briefing",
"requestId": "01JC…",
"retryAfter": 2
}Each type has its own documentation page.
| Status | Types |
|---|---|
| 400 |
invalid-parameter (with errors[]), invalid-cursor, window-required, window-too-large, key-in-query
|
| 401 |
missing-key, invalid-key, key-expired, key-revoked
|
| 403 |
scope-denied, source-not-permitted, terms-not-accepted
|
| 404 |
not-found, feature-disabled
|
| 405, 406, 412, 413, 414, 415, 431 | protocol refusals, see [[Spec: Errors |
| 422 |
ambiguous-place (with candidates[]), outside-coverage, area-too-large, invalid-section
|
| 429 |
rate-limited, quota-exceeded, overloaded (all with Retry-After) |
| 500 |
internal (never with internal detail; the request id links to the log) |
| 503 |
deadline-exhausted, upstream-unavailable, not-ready
|
409 is not used: the API is read-only. 504 comes only from the TLS edge, never from the service. The complete catalogue is in Spec: Errors.
Every response carries RateLimit-Policy and RateLimit (IETF HTTP API working group draft). Every 429 carries Retry-After. See Rate Limits and Priority.
- The major version is in the path (
/v1). Within v1, changes are additive only. - A breaking change goes to
/v2, published beside v1. The old version then carriesDeprecation(RFC 9745),Sunset(RFC 8594) andLink rel="deprecation"headers, with at least six months' notice. - The OpenAPI document is generated from code and every pull request is checked for breaking changes against
main; a breaking change without a major version bump fails CI. - The API's version moves in step with the ViaFrei platform's version.
GET /v1/metareportsapiVersion,platformVersionandcontractVersion.
- Generated from the code (code-first), exported to a committed file, served at
/openapi.jsonand rendered at/docs. - Every operation has a summary, a description, its scope, its source families, its MCP counterpart where one exists, and examples that are executed against fixtures in CI.
- A docs lint fails when an operation lacks any of them.
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