Repository navigation
Data Model Parking
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 parking facilities (garages, lots, park and ride, rest areas, lorry parking) with their capacity per vehicle class and their live occupancy, and sharing stations with their live count of available vehicles.
erDiagram
parking_facility ||--o{ facility_capacity : "offers"
parking_facility ||--o{ occupancy_observation : "reports"
road |o--o{ parking_facility : "serves"
sharing_station ||--o{ sharing_availability_observation : "reports"
source ||--o{ parking_facility : "describes"
source ||--o{ occupancy_observation : "describes"
source ||--o{ sharing_station : "describes"
parking_facility {
string facility_id PK
string name
string parking_kind
string operator_name
string road_ref FK
string direction
point location
polygon outline
bool acceptance_required
string source_ref FK
}
facility_capacity {
string facility_id FK
string vehicle_class
int total_spaces
}
occupancy_observation {
string facility_id FK
instant observed_at
int free_spaces
int total_spaces
string occupancy_status
string source_ref FK
}
sharing_station {
string station_id PK
string name
string operator_name
string vehicle_class
point location
string source_ref FK
}
sharing_availability_observation {
string station_id FK
instant observed_at
int available_vehicles
}
A place to park. Withdrawn facilities are soft-closed and kept: "this rest area no longer exists" is an answer. Retention REF.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
facility_id |
id |
yes | Identity |
id (pk_…) |
||
name |
text |
no | Name as published | name |
||
parking_kind |
enum<parking_kind> |
yes |
garage, lot, park_and_ride, rest_area, truck_parking, on_street, other
|
What it is |
kind, kind filter |
|
operator_name |
text |
no | Operator as published | none in v1 | ||
road_ref |
key → road
|
no | The motorway it serves, for rest areas and lorry parking | corridor matching | ||
direction |
enum<direction> |
no | Carriageway it is reached from | corridor matching | ||
location |
point |
yes | WGS 84 | Position of the entrance or centre |
location, distanceM, distanceAlongKm, detourM
|
|
outline |
polygon |
no | WGS 84 | Area, where published |
geometry (full) |
|
acceptance_required |
bool |
yes | True when the occupancy of this facility is served only after the key holder accepted the source's terms (SEC-030) | termsRequired |
||
| envelope | sourceFamily |
Spaces per vehicle class, as published. A facility without published capacity has no rows. Retention REF.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
facility_id |
id → parking_facility
|
yes | The facility | none | ||
vehicle_class |
enum<vehicle_class> |
yes |
car, lorry, coach, motorhome, disabled, all
|
Who the spaces are for |
vehicleClasses[], capacity.byVehicle, vehicle filter |
|
total_spaces |
int |
yes | ≥ 0 | Number of spaces |
capacity.total (row all), capacity.byVehicle
|
One live reading of a facility. Retention OBS; the current occupancy is the newest reading inside the family's freshness horizon, otherwise none (occupancy: null, FR-PARK-002).
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
facility_id |
id → parking_facility
|
yes | The facility | parent item | ||
observed_at |
instant |
yes | UTC | When the reading was true per the source | occupancy.observedAt |
|
free_spaces |
int |
no | ≥ 0 | Free spaces, where published |
occupancy.free, free_min filter, sort=free
|
|
total_spaces |
int |
no | ≥ free_spaces
|
Spaces counted in this reading, which may differ from the static capacity | none | |
occupancy_status |
enum<occupancy_status> |
yes |
free, filling, full, closed, unknown
|
Published or mapped status | occupancy.state |
|
source_ref |
key → source
|
yes | Source of the reading; may differ from the facility's | sourceFamily |
occupancy.trend is not stored: it is a domain rule over the readings of a configured recent window (rising, falling, steady, unknown).
A fixed station of a vehicle-sharing scheme. Retention REF.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
station_id |
id |
yes | Identity |
id (sh_…) |
||
name |
text |
no | Name as published | name |
||
operator_name |
text |
no | Scheme operator | operator |
||
vehicle_class |
enum<vehicle_class> |
yes |
car in v1 |
Vehicles offered |
vehicle filter |
|
location |
point |
yes | WGS 84 | Position |
location, distanceM
|
|
| envelope | sourceFamily |
One live count of vehicles at a station. Retention OBS.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
station_id |
id → sharing_station
|
yes | The station | parent item | ||
observed_at |
instant |
yes | UTC | When the count was true | vehiclesAvailable.observedAt |
|
available_vehicles |
int |
no | ≥ 0 | Vehicles available | vehiclesAvailable |
| Relationship | Cardinality | Rule |
|---|---|---|
parking_facility → facility_capacity
|
one to many | One row per vehicle class at most |
parking_facility → occupancy_observation
|
one to many | Most facilities have none: no live reading is published |
parking_facility → road
|
many to zero-or-one | Only for facilities on a motorway |
sharing_station → sharing_availability_observation
|
one to many |
A facility's natural key is unique only within its source; the same rest area described by two sources is two records unless a documented matching rule links them. Each record keeps its own licence (DM-011).
- Facilities and stations:
REF, soft-closed when withdrawn. - Occupancy and availability:
OBS, append-only, horizon configurable. A reading older than the family's stale threshold is reported withstalefreshness. - Occupancy is never inferred from capacity (FR-PARK-002, ENV-041).
| Path | Used by |
|---|---|
Nearest facilities within a radius, filtered by vehicle_class and parking_kind, with the newest reading |
parking options, near |
Along a corridor: road_ref and direction for motorway facilities, plus a buffered line for the rest |
parking options, along; route briefing |
| Nearest stations within a radius, with the newest count | sharing options |
Parking data reaches the read side under several licences, so the licence is a property of each record, not of the domain. Share-alike facilities and their readings stay in records of their own source and carry the share-alike flag and offer. Facilities whose source requires the key holder's acceptance of terms have acceptance_required set; their occupancy is withheld until acceptance (FR-PARK-003).
| Entity | Operations | Resource members |
|---|---|---|
parking_facility, facility_capacity
|
GET/POST /v1/parking-options, route briefing parking part |
parking item, capacity
|
occupancy_observation |
parking options | occupancy |
sharing_station, sharing_availability_observation
|
GET /v1/sharing-options |
sharing item |
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