Skip to content

Spec Endpoints Energy and Parking

mavrovde edited this page Nov 1, 2026 · 2 revisions

Spec: Endpoints, Energy and Parking

Part of the Technical Specification. Requirement prefixes: FR-ENERGY, FR-PARK. Shared inputs and types: Spec: Resource Model. Scopes: energy, parking.

All four operations accept near (at/place/q with radius_m) or along (motorway section or route with buffer_m); "along" answers add distanceAlongKm (from the corridor start, one decimal) and detourM (distance from the corridor line). A query POST with the same parameters is accepted for long routes (PROT-012).

1. Refuel options

GET|POST /v1/refuel-options · operationId listRefuelOptions · MCP counterparts: fuel station search, cheapest fuel, hydrogen station search · cache family: fuel

Parameter Type Required Default Meaning
location (near or along) yes
product open enum e5, e10, diesel, lpg, cng, lng, h2 no all Products with a price
sort distance, price no distance price requires exactly one product; ties by distance, then id
open_now boolean no false Only stations known to be open
limit, cursor, fields, geometry, lang no 20 (max 100)
{
  "data": [
    {
      "id": "fs_m2Lq",
      "name": "Example station",
      "brand": "Example",
      "location": {"lat": 52.520008, "lon": 13.404954},
      "address": {"street": "Example Street", "houseNumber": "5", "postcode": "10178", "locality": "Berlin", "state": "DE-BE"},
      "distanceM": 640,
      "openingState": "open",
      "offers": [
        {
          "product": "e10",
          "price": {"amount": "1.689", "currency": "EUR"},
          "unit": "litre",
          "observedAt": "2026-11-01T12:51:00Z",
          "observedAtLocal": "2026-11-01T13:51:00+01:00"
        }
      ],
      "sourceFamily": "energy.fuel"
    }
  ]
}
Field Meaning
offers[].unit litre, or kilogram for h2, cng and lng
offers[].price Price per unit including VAT, as published; three decimals for fuels
openingState open, closed, unknown at meta.generatedAt
A station without a current price for a requested product listed with offers: [] only when sort=distance; never listed when sort=price

2. Charging options

GET|POST /v1/charging-options · operationId listChargingOptions · MCP counterpart: charging station search · cache family: charging

Parameter Type Default Meaning
min_kw number 0 Minimum maximum power of at least one connector
connector list of open enum type2, ccs2, chademo, type1, ccs1, schuko, nacs, other all
available_now boolean false Only sites with at least one point in state available observed within freshness.stale_after.charging
access public, restricted, all public
sort distance, power distance power sorts by maximum power descending

Item: see the complete example on Spec: Common Envelope. Availability state is an open enum available, occupied, reserved, out_of_order, unknown; summary.availableNow is null when no point has a live state. Tariffs are not part of v1.

3. Parking options

GET|POST /v1/parking-options · operationId listParkingOptions · MCP counterpart: parking search · cache family: parking

Parameter Type Default Meaning
vehicle car, lorry, coach, motorhome car Suitable sites only
kind list of open enum garage, lot, park_and_ride, rest_area, truck_parking, on_street, other all
free_min integer 0 Only sites with at least this many free spaces in a live reading
sort distance, free distance
{
  "data": [
    {
      "id": "pk_x81P",
      "name": "Example rest area",
      "kind": "rest_area",
      "vehicleClasses": ["car", "lorry"],
      "location": {"lat": 49.452103, "lon": 11.076665},
      "distanceAlongKm": 41.3,
      "detourM": 0,
      "capacity": {"total": 120, "byVehicle": {"lorry": 60, "car": 60}},
      "occupancy": {
        "free": 14, "state": "filling", "trend": "rising",
        "observedAt": "2026-11-01T12:55:00Z", "observedAtLocal": "2026-11-01T13:55:00+01:00"
      },
      "termsRequired": false,
      "sourceFamily": "parking.live"
    }
  ]
}

occupancy is null where no live reading is published (ENV-041). state is an open enum free, filling, full, closed, unknown; trend rising, falling, steady, unknown.

Terms-gated data. Where a source requires the key holder's explicit acceptance of terms, the occupancy of such sites is returned only after acceptance (SEC-030); before it, the site is listed with occupancy: null and termsRequired: true, and meta.warnings[] carries partial.

4. Sharing options

GET /v1/sharing-options · operationId listSharingOptions · MCP counterpart: sharing search · cache family: parking. Near only. Parameter vehicle (car, default). Item: id (sh_…), name, operator, location, distanceM, vehiclesAvailable (integer, nullable, Observed), sourceFamily.

Requirements

ID Requirement Verification
FR-ENERGY-001 Prices MUST be returned as Money with the source's precision and the unit; arithmetic and ordering on prices MUST use exact decimal comparison. Unit
FR-ENERGY-002 sort=price MUST require exactly one product and MUST exclude stations without a current price for it; ties MUST break by distance, then id. Handler
FR-ENERGY-003 Hydrogen MUST be served by refuel options as product h2 with unit kilogram. Parity
FR-ENERGY-004 Every price and every charge-point state MUST carry its observation instant; a value older than the family's stale threshold MUST set stale in meta.freshness and the data_stale warning. Contract
FR-ENERGY-005 Energy price data whose licence restricts the use class (for example consumer information only) MUST be served only to plans whose use class the licence permits (SEC-031). Security
FR-ENERGY-006 Charging options MUST filter by min_kw, connector, available_now and access exactly as documented. Handler
FR-ENERGY-007 "Along" answers MUST report distanceAlongKm and detourM, and MUST order by distanceAlongKm when sort=distance. Unit
FR-PARK-001 Parking options MUST return only sites suitable for the requested vehicle. Handler
FR-PARK-002 Occupancy MUST be null where no live reading exists; it MUST never be inferred from capacity. Mapping
FR-PARK-003 Terms-gated occupancy MUST be withheld until the key's acceptance is recorded, and the withholding MUST be visible as termsRequired and a partial warning. Security
FR-PARK-004 Sharing options MUST report available vehicles only with an observation instant. Contract

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally