Skip to content

Spec Endpoints Weather Rules and Composed

mavrovde edited this page Nov 1, 2026 · 1 revision

Spec: Endpoints, Weather Risk, Driving Rules and Composed Features

Part of the Technical Specification. Requirement prefixes: FR-WEATHER, FR-RULES, FR-BRIEF. Shared inputs and types: Spec: Resource Model.

1. Weather risk

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.

2. Driving rules

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."
  }
}

3. Route briefing (composed)

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]
Loading

4. Place overview (composed)

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.

Requirements

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

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally