Repository navigation
Data Model Energy
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, Energy and Parking.
The domain holds the places a vehicle takes on energy: fuel stations with their products and prices (hydrogen included, as a product), and charging sites with their charge points, connectors and live states.
erDiagram
fuel_station ||--o{ opening_period : "opens during"
fuel_station ||--o{ fuel_price_observation : "is priced by"
fuel_product ||--o{ fuel_price_observation : "prices"
charging_site ||--|{ charge_point : "groups"
charge_point ||--|{ connector : "offers"
charge_point ||--o{ charge_point_state_observation : "reports"
source ||--o{ fuel_station : "describes"
source ||--o{ fuel_price_observation : "describes"
source ||--o{ charging_site : "describes"
source ||--o{ charge_point_state_observation : "describes"
fuel_station {
string station_id PK
string name
string brand
string street
string house_number
string postcode
string locality
string region_code FK
point location
string open_state
instant open_state_at
string source_ref FK
}
opening_period {
string station_id FK
int weekday
time opens_at
time closes_at
bool public_holiday
}
fuel_product {
string product_code PK
string label
string price_unit
}
fuel_price_observation {
string station_id FK
string product_code FK
instant observed_at
decimal price
string currency
string source_ref FK
}
charging_site {
string site_id PK
string name
string operator_name
string access
string street
string postcode
string locality
point location
string source_ref FK
}
charge_point {
string point_id PK
string site_id FK
string evse_code
string current_kind
decimal power_max_kw
point location
}
connector {
string point_id FK
int position
string connector_type
string plug_standard
string cable
decimal power_max_kw
}
charge_point_state_observation {
string point_id FK
instant observed_at
string availability
string source_ref FK
}
A filling station. Its open state is a current-state field kept in step with the newest published state. Retention REF for the station, CUR for open_state.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
station_id |
id |
yes | Identity |
id (fs_…) |
||
name |
text |
yes | Name as published | name |
||
brand |
text |
no | Brand as published | brand |
||
street, house_number, postcode, locality
|
text |
no | postcode five digits | Address | address |
|
region_code |
key → admin_region
|
no | ISO 3166-2 for the state | Enclosing region | address.state |
|
location |
point |
yes | WGS 84 | Position |
location, distanceM, distanceAlongKm, detourM
|
|
open_state |
enum<open_state> |
yes |
open, closed, unknown
|
Whether the station is open, as last published | openingState |
|
open_state_at |
instant |
no | UTC | When open_state was observed |
freshness of openingState
|
|
| envelope | sourceFamily |
Published opening hours, one row per weekday interval. Retention REF.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
station_id |
id → fuel_station
|
yes | The station | none | ||
weekday |
int |
yes | ISO weekday | 1 (Monday) to 7 | Day |
open_now filter |
opens_at, closes_at
|
time |
yes | Europe/Berlin wall clock |
closes_at may be ≤ opens_at for a period past midnight |
Interval |
open_now filter |
public_holiday |
bool |
yes | True when the row applies on public holidays instead of the weekday |
open_now filter |
The code list of products a price can be for. Retention REF; a fixed list of the API.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
product_code |
enum<fuel_type> |
yes |
e5, e10, diesel, lpg, cng, lng, h2
|
Product |
offers[].product, product filter |
|
label |
ltext |
yes | Display name | documentation | ||
price_unit |
enum<price_unit> |
yes |
litre, kilogram
|
Unit the price is per (kilogram for h2, cng, lng) |
offers[].unit |
One published price of one product at one station at one instant. A new observation is added when the price changes; none is ever updated. The current price of a product at a station is the newest observation inside the source's freshness horizon. Retention OBS.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
station_id |
id → fuel_station
|
yes | The station | parent item | ||
product_code |
enum<fuel_type> → fuel_product
|
yes | The product | offers[].product |
||
observed_at |
instant |
yes | UTC | When the price was valid per the source | offers[].observedAt |
|
price |
decimal(6,3) |
yes | per price_unit, VAT included |
> 0 | Price as published | offers[].price.amount |
currency |
currency |
yes | ISO 4217 | EUR |
Currency | offers[].price.currency |
source_ref |
key → source
|
yes | Source of the price; may differ from the station's |
sourceFamily, meta.notes.purpose[]
|
A location with one or more charge points under one operator. Retention REF.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
site_id |
id |
yes | Identity |
id (cs_…) |
||
name |
text |
no | Name as published | name |
||
operator_name |
text |
no | Operator as published | operator |
||
access |
enum<access> |
yes |
public, restricted, unknown
|
Who may use it |
access, access filter |
|
street, house_number, postcode, locality
|
text |
no | Address |
address (when selected) |
||
location |
point |
yes | WGS 84 | Position |
location, distanceM
|
|
| envelope | sourceFamily |
One point that charges one vehicle at a time (an EVSE). Retention REF.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
point_id |
id |
yes | Identity | chargePoints[].id |
||
site_id |
id → charging_site
|
yes | Owning site | parent item | ||
evse_code |
key |
no | the European EVSE identifier format | Public identifier of the point, where published | none in v1 | |
current_kind |
enum<current_kind> |
no |
ac, dc
|
Current type | none in v1 | |
power_max_kw |
decimal(7,2) |
no | kW | > 0 | Highest power of any connector |
summary.maxPowerKw, min_kw filter, sort=power
|
location |
point |
no | WGS 84 | Position when it differs from the site | none |
A plug or socket on a charge point. Retention REF.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
point_id |
id → charge_point
|
yes | Owning point | none | ||
position |
int |
yes | ≥ 1, unique per point | Order | array order | |
connector_type |
enum<connector_type> |
yes | see dictionary | The plug family the API speaks |
connectors[].type, connector filter |
|
plug_standard |
enum<plug_standard> |
no | see dictionary | The formal standard as published, from which connector_type is mapped |
none | |
cable |
enum<cable> |
yes |
attached, socket, unknown
|
Whether a cable is attached | none in v1 | |
power_max_kw |
decimal(7,2) |
no | kW | > 0 | Highest power of this connector | connectors[].maxPowerKw |
One live state of one charge point at one instant. Retention OBS; the current state is the newest observation inside freshness.stale_after.charging, otherwise unknown.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
point_id |
id → charge_point
|
yes | The point | parent item | ||
observed_at |
instant |
yes | UTC | When the state was true per the source | availability.observedAt |
|
availability |
enum<availability> |
yes |
available, occupied, reserved, out_of_order, unknown
|
State, mapped from the published state and operational status |
availability.state, summary.availableNow, available_now filter |
|
source_ref |
key → source
|
yes | Source of the state; may differ from the site's | sourceFamily |
Tariffs are not part of the v1 read model.
| Relationship | Cardinality | Rule |
|---|---|---|
fuel_station → opening_period
|
one to many | None when hours are not published |
fuel_station → fuel_price_observation
|
one to many | A station may have no price |
fuel_product → fuel_price_observation
|
one to many | Closed list |
charging_site → charge_point
|
one to one-or-more | A site without points is not served |
charge_point → connector
|
one to one-or-more | |
charge_point → charge_point_state_observation
|
one to many | A point may have no live state |
A price or a state may come from a different source than its station or site. It is linked by the publisher's key for the station or point, matched within the documented pairing of those two sources, and carries its own source_ref.
- Stations, sites, points and connectors are reference records (
REF). - Prices and charge-point states are observations (
OBS), append-only. A value older than the family's stale threshold is served withstalefreshness (FR-ENERGY-004), never as current without that flag. - Opening hours are reference data; the current
open_stateis a current-state field (CUR).
| Path | Used by |
|---|---|
| Nearest stations within a radius, then the newest price per product | refuel options, near |
| Along a corridor, ordered by distance along it, with distance from the line | refuel options and charging options, along; route briefing |
| Nearest stations with a current price for one product, ordered by price, then distance, then id | refuel options, sort=price
|
| Nearest sites within a radius filtered by connector type, power and access, with the newest state per point | charging options |
By key on site_id or station_id
|
id resolution |
Prices and live states name their own source, which can carry a purpose restriction (for example consumer information only): such records are served only to plans whose use class the source permits, with the purpose note verbatim (FR-ENERGY-005, LIC-006). The station or site record's source is attributed beside it.
| Entity | Operations | Resource members |
|---|---|---|
fuel_station, opening_period
|
GET/POST /v1/refuel-options
|
refuel item |
fuel_product, fuel_price_observation
|
refuel options, route briefing fuel part |
offers[] |
charging_site, charge_point, connector
|
GET/POST /v1/charging-options
|
charging item, chargePoints[], connectors[]
|
charge_point_state_observation |
charging options |
availability, summary.availableNow
|
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