Repository navigation
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).
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
|
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.
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.
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.
| 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 |
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