Skip to content

Data Model Energy

mavrovde edited this page Nov 1, 2026 · 1 revision

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.

1. Diagram

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

2. Fuel

fuel_station

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

opening_period

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

fuel_product

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

fuel_price_observation

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

3. Charging

charging_site

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

charge_point

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

connector

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

charge_point_state_observation

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.

4. Keys and relationships

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.

5. Temporal behaviour

  • 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 with stale freshness (FR-ENERGY-004), never as current without that flag.
  • Opening hours are reference data; the current open_state is a current-state field (CUR).

6. Access paths

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

7. Licence and attribution

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.

8. Entity to API

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.

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally