Repository navigation
Data Model Weather
Part of the Data Model. A logical model for the API's read side, not a copy of any physical schema; storage names may differ. Conventions, the record envelope and retention classes: Data Model section 5. API side: Endpoints, Weather Risk, Driving Rules and Composed Features section 1.
The domain holds official weather warnings and the warning areas they cover, and road weather observations from stations beside the road. Warnings are official texts: their levels are never re-graded and their original wording is always kept.
erDiagram
weather_warning ||--|{ warning_coverage : "covers"
warning_area ||--o{ warning_coverage : "is covered by"
admin_region |o--o{ warning_area : "matches"
road_weather_station ||--o{ road_weather_observation : "reports"
road |o--o{ road_weather_station : "is watched by"
source ||--o{ weather_warning : "describes"
source ||--o{ road_weather_station : "describes"
weather_warning {
string warning_id PK
string hazard
int warning_level
string level_label
string message_status
string issuer_name
string headline
string description
string instruction
string text_lang
instant valid_from
instant valid_to
instant published_at
string source_ref FK
}
warning_area {
string area_id PK
string area_name
string area_kind
string region_code FK
polygon boundary
}
warning_coverage {
string warning_id FK
string area_id FK
}
road_weather_station {
string station_id PK
string name
string road_ref FK
point location
string source_ref FK
}
road_weather_observation {
string station_id FK
instant observed_at
string surface_state
decimal surface_temp_c
decimal air_temp_c
decimal dew_point_c
}
One official warning in its current version. Retention: event record; each version is also kept as an observation (OBS); a warning that has expired or been cancelled leaves the read side after a configurable grace period (TRN).
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
warning_id |
id |
yes | Identity |
id (ww_…) |
||
hazard |
enum<hazard> |
yes | see dictionary | What the warning is about, mapped from the issuer's event code |
hazard, hazards filter |
|
warning_level |
int |
yes | 0 to 4; 0 is advance information | The issuer's level, unchanged (FR-WEATHER-002) |
level, min_level filter |
|
level_label |
ltext |
yes | The issuer's name for the level | levelName |
||
message_status |
enum<message_status> |
yes |
issued, updated, cancelled
|
Lifecycle of the message | visibility (a cancelled warning is not active) | |
issuer_name |
text |
yes | The issuing authority | issuer |
||
headline |
ltext |
yes | official wording | Headline | headline |
|
description |
ltext |
no | official wording | The official text, never edited | description |
|
instruction |
ltext |
no | official wording | The official advice | instruction |
|
text_lang |
text |
yes | BCP 47 | Language of the original wording | originalLanguage |
|
valid_from |
instant |
yes | UTC | Onset | validity.from |
|
valid_to |
instant |
no | UTC | null = until further notice | Expiry | validity.until |
published_at |
instant |
no | UTC | When the issuer sent this version | none in v1 | |
| envelope | sourceFamily |
Levels 1 to 4 are served; level 0 (advance information) is held but served only when an operation asks for it.
An area the issuer warns for (a county, a municipality, a coastal strip, a lake), with its outline. Retention REF.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
area_id |
id |
yes | Identity | none | ||
area_name |
text |
yes | The issuer's name for the area | area.name |
||
area_kind |
enum<area_kind> |
yes |
county, municipality, coast, lake, sea, other
|
Kind of area | none in v1 | |
region_code |
key → admin_region
|
no | The administrative region it matches, where one does | place overview | ||
boundary |
polygon |
yes | WGS 84 | valid polygon | Outline |
area.geometry (with geometry=), intersection |
Which areas a warning covers. Link entity, no envelope.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
warning_id |
id → weather_warning
|
yes | Warning | none | ||
area_id |
id → warning_area
|
yes | unique with warning_id
|
Covered area | area |
A measuring station beside a road. Retention REF.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
station_id |
id |
yes | Identity | none | ||
name |
text |
no | Name as published | none in v1 | ||
road_ref |
key → road
|
no | Road it watches | corridor matching | ||
location |
point |
yes | WGS 84 | Position | roadWeather[].location |
|
| envelope | roadWeather[].sourceFamily |
One measurement at a station. Retention OBS; never a forecast (FR-WEATHER-004).
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
station_id |
id → road_weather_station
|
yes | Station | parent | ||
observed_at |
instant |
yes | UTC | Measurement instant | roadWeather[].observedAt |
|
surface_state |
enum<surface_state> |
no |
dry, damp, wet, ice, snow, frost, unknown
|
Road surface | roadWeather[].surfaceState |
|
surface_temp_c |
decimal(4,1) |
no | °C | Surface temperature | roadWeather[].surfaceTempC |
|
air_temp_c |
decimal(4,1) |
no | °C | Air temperature | roadWeather[].airTempC |
|
dew_point_c |
decimal(4,1) |
no | °C | Dew point | none in v1 |
| Relationship | Cardinality | Rule |
|---|---|---|
weather_warning ↔ warning_area
|
many to many through warning_coverage
|
A warning covers at least one area |
warning_area → admin_region
|
many to zero-or-one | |
road_weather_station → road_weather_observation
|
one to many | |
road_weather_station → road
|
many to zero-or-one |
A warning's natural key is the issuer's message identifier within its source; an update of the same warning is a new version of the same record.
- A warning is active at t when
valid_from≤ t <valid_to(orvalid_tois null), it is not cancelled and not withdrawn. Look-ahead widens t toweather.max_lookahead_h. - Each new version is appended as an observation; the current version is replaced in place.
- Road weather is
OBS: the newest observation per station inside the family's freshness horizon is the current one.
| Path | Used by |
|---|---|
Areas whose boundary contains a point, then their active warnings |
weather risk, near |
Areas whose boundary intersects a buffered corridor |
weather risk, along; route briefing |
Stations along a corridor (by road_ref or buffered line), newest observation each |
roadWeather[] |
Warnings are official texts: the issuer is carried, levels are unchanged, and the original wording stays available beside any translation (FR-WEATHER-003). Translations are text_variant rows marked with their origin (Provenance).
| Entity | Operations | Resource members |
|---|---|---|
weather_warning, warning_coverage, warning_area
|
GET/POST /v1/weather-risk, route briefing and place overview weather part |
warnings[] |
road_weather_station, road_weather_observation
|
weather risk, along | roadWeather[] |
The lamp of a weather answer is a domain rule over the active warning levels, not stored. Field-level mapping: Mapping.
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