Repository navigation
Spec Endpoints Weather Rules and Composed
Part of the Technical Specification. Requirement prefixes: FR-WEATHER, FR-RULES, FR-BRIEF. Shared inputs and types: Spec: Resource Model.
GET|POST /v1/weather-risk · operationId getWeatherRisk · MCP counterpart: weather warnings check · scope weather · cache family: weather
Location: near (at/place/q) or along (section or route). Parameters: active_at (instant, default now, up to weather.max_lookahead_h), min_level (1–4, default 1), hazards (list), lang.
{
"data": {
"lamp": "amber",
"warnings": [
{
"id": "ww_9Ke",
"hazard": "ice",
"level": 2,
"levelName": "Markante Wetterwarnung",
"issuer": "national weather service",
"headline": "Warning of slippery ice",
"description": "…",
"instruction": "…",
"textLanguage": "en",
"originalLanguage": "de",
"validity": {"from": "2026-11-01T17:00:00Z", "fromLocal": "2026-11-01T18:00:00+01:00", "until": "2026-11-02T08:00:00Z", "untilLocal": "2026-11-02T09:00:00+01:00"},
"area": {"name": "Kreis Example", "geometry": null},
"distanceAlongKm": null,
"sourceFamily": "weather.official_warnings"
}
],
"roadWeather": [
{
"location": {"lat": 48.3, "lon": 10.9},
"surfaceState": "wet",
"surfaceTempC": 1.5,
"airTempC": 3.0,
"observedAt": "2026-11-01T12:50:00Z", "observedAtLocal": "2026-11-01T13:50:00+01:00",
"sourceFamily": "weather.road_stations"
}
]
}
}| Field | Meaning |
|---|---|
hazard |
open enum thunderstorm, wind, rain, snow, ice, fog, heat, frost, uv, flood, other
|
level |
Official level 1 (minor) to 4 (extreme), as issued |
headline, description, instruction
|
In meta.language when a translation exists; the original official wording is always available with original=true (FR-WEATHER-003) |
roadWeather |
Present only for "along" queries and when road weather observations exist near the corridor; otherwise []
|
Order: level descending, then validity.from ascending, then id.
GET /v1/driving-rules · operationId getDrivingRules · MCP counterpart: driving rules · scope rules · cache family: rules
Parameters: topic (open enum, for example lorry_sunday_ban, holiday_ban, speed_limits, winter_tyres, emission_zones, emergency_corridor; required), vehicle (car, lorry, motorhome, motorcycle, optional), lang.
{
"data": {
"topic": "lorry_sunday_ban",
"title": "Sunday and public-holiday driving ban for lorries",
"rules": [{"text": "…", "appliesTo": ["lorry"], "legalBasis": "…"}],
"reviewedOn": "2026-10-01",
"disclaimer": "Informational, not legal advice."
}
}GET|POST /v1/route-briefing · operationId getRouteBriefing · scopes per part · cache: minimum of parts
Purpose. "What should I know along this route?" in one answer.
| Parameter | Type | Required | Default | Meaning |
|---|---|---|---|---|
road + direction + from/to (or from_km/to_km) |
one form required | A motorway section | ||
route + buffer_m
|
one form required | A client route | ||
needs |
list of roads, weather, fuel, charging, parking
|
no | all permitted to the key | Parts to compute |
departure_at |
instant | no | now | Start of the horizon |
horizon_min |
integer | no |
briefing.default_horizon_min (design 180) |
1 – briefing.max_horizon_min (design 720) |
vehicle, product, min_kw
|
no | Passed to the energy and parking parts | ||
per_part_limit |
integer | no | 5 | 1 – 20 items per part |
{
"data": {
"corridor": {"road": "A7", "direction": "south", "fromKm": 0.0, "toKm": 151.0, "fromName": "Hamburg", "toName": "Hannover"},
"lamp": "red",
"lampReason": "road_closed",
"roads": {"situations": [ ]},
"weather": {"warnings": [ ]},
"fuel": {"stops": [ ]},
"charging": {"sites": [ ]},
"parking": {"sites": [ ]}
},
"meta": {
"parts": [
{"part": "roads", "status": "ok"},
{"part": "weather", "status": "ok"},
{"part": "fuel", "status": "not_permitted", "problemType": "https://api.viafrei.de/problems/source-not-permitted"},
{"part": "charging", "status": "ok"},
{"part": "parking", "status": "timeout"}
]
}
}A part with a status other than ok is absent from data. The overall lamp is the worst lamp of the ok parts; when a safety part (roads, weather) is not ok, the lamp is unknown unless another part already gives red.
flowchart TD
S[Validated request] --> G[Licence gate per part]
G --> P{Permits available<br/>for parallel parts?}
P -->|yes| PAR[Run parts in parallel,<br/>each with a sub-deadline]
P -->|no| SEQ[Run parts in priority order:<br/>roads, weather, energy, parking]
PAR --> A[Assemble]
SEQ --> A
A --> C{Any part ok?}
C -->|yes| OK[200 with part statuses]
C -->|no| F[503 with the worst part problem]
GET /v1/places/{placeId}/overview · operationId getPlaceOverview. Parameters: needs (roads, weather, fuel, charging, parking, transit, accessibility), radius_m, per_part_limit. Same part semantics as the route briefing, with an area lamp.
| ID | Requirement | Verification |
|---|---|---|
| FR-WEATHER-001 | Weather risk MUST return every official warning whose area intersects the point or corridor and whose validity contains active_at or starts within the look-ahead. |
Unit |
| FR-WEATHER-002 | Levels MUST be the issuer's levels 1–4 unchanged; the service MUST NOT re-grade them. | Mapping |
| FR-WEATHER-003 | Warning texts MUST be available in the original official wording (original=true); a translation MUST be tagged with textLanguage and originalLanguage and MUST NOT replace the original. |
Handler |
| FR-WEATHER-004 | Road weather observations MUST carry their observation instant and MUST NOT be presented as forecasts. | Contract |
| FR-RULES-001 | Every rule topic MUST carry reviewedOn and the disclaimer that it is informational, not legal advice. |
Contract |
| FR-RULES-002 | Rule texts MUST be identical to the MCP server's for the same topic, vehicle and language. | Parity |
| FR-BRIEF-001 | The route briefing MUST accept a motorway section or a client route, and MUST NOT compute a route between places. | Handler |
| FR-BRIEF-002 | Each part MUST be gated by the licence gate on its own; a part the key may not read MUST NOT be queried and MUST be reported not_permitted. |
Security |
| FR-BRIEF-003 | Parts MUST run with bounded parallelism (compose.max_parallel), one admission permit each, and each with a sub-deadline (compose.part_deadline) within the request deadline. |
Load |
| FR-BRIEF-004 | Under permit pressure, parts MUST run sequentially in the order roads, weather, energy, parking, and parts that cannot start in time MUST be reported timeout. |
Unit |
| FR-BRIEF-005 | The answer MUST be 200 when at least one part is ok, with every part's status in meta.parts; it MUST be 503 only when no part is ok. |
Handler |
| FR-BRIEF-006 | The overall lamp MUST be unknown when a safety part is missing, unless another part already yields red. |
Unit |
| FR-BRIEF-007 | The entity tag of a composed answer MUST combine the freshness versions of every family read, so an unchanged briefing answers 304 without reading storage. |
Unit |
| FR-BRIEF-008 | The place overview MUST follow FR-BRIEF-002 to FR-BRIEF-007 with an area instead of a corridor. | Handler |
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