Repository navigation
Spec Resource Model
Part of the Technical Specification. Requirement prefixes: FR-LOC (shared inputs) and FR-GEN (rules for every operation). The model follows the bounded contexts of the Domain Model: domains and features, never storage. No table, view or column of any store appears in a path, a parameter or a payload. The logical entities each operation composes, and the trace from every public field to them, are on Data Model and Data Model: Mapping.
| Domain | Operation | Method and path | Scope | Cache family | Specified on |
|---|---|---|---|---|---|
| Places | Search places | GET /v1/places |
places | places | [[Places |
| Places | Get a place | GET /v1/places/{placeId} |
places | places | [[Places |
| Places | Describe a point | GET /v1/locations/describe |
places | places | [[Places |
| Places | Search addresses | GET /v1/addresses |
places | places | [[Places |
| Places | Points of interest | GET /v1/points-of-interest |
places | places | [[Places |
| Roads | List motorways | GET /v1/motorways |
roads | roads | [[Roads |
| Roads | Motorway conditions | GET /v1/motorways/{road}/conditions |
roads | roads | [[Roads |
| Roads | Roadworks ahead | GET /v1/motorways/{road}/roadworks-ahead |
roads | roads | [[Roads |
| Roads | Conditions in an area | GET /v1/road-conditions |
roads | roads | [[Roads |
| Roads | Get a situation | GET /v1/road-situations/{situationId} |
roads | roads | [[Roads |
| Roads | Condition history | GET /v1/motorways/{road}/conditions/history |
roads + history | none (immutable window) | [[Roads |
| Energy | Refuel options |
GET/POST /v1/refuel-options
|
energy | fuel | [[Energy and Parking |
| Energy | Charging options |
GET/POST /v1/charging-options
|
energy | charging | [[Energy and Parking |
| Parking | Parking options |
GET/POST /v1/parking-options
|
parking | parking | [[Energy and Parking |
| Parking | Sharing options | GET /v1/sharing-options |
parking | parking | [[Energy and Parking |
| Public transport | Search stop places | GET /v1/stop-places |
transit | places | [[Transit and Accessibility |
| Public transport | Departures | GET /v1/stop-places/{stopPlaceId}/departures |
transit | departures | [[Transit and Accessibility |
| Public transport | Disruptions at a stop | GET /v1/stop-places/{stopPlaceId}/disruptions |
transit | departures | [[Transit and Accessibility |
| Public transport | Disruptions in an area | GET /v1/disruptions |
transit | departures | [[Transit and Accessibility |
| Accessibility | Station accessibility | GET /v1/stop-places/{stopPlaceId}/accessibility |
accessibility | accessibility | [[Transit and Accessibility |
| Weather risk | Weather risk |
GET/POST /v1/weather-risk
|
weather | weather | [[Weather, Rules and Composed |
| Driving rules | Rule topic | GET /v1/driving-rules |
rules | rules | [[Weather, Rules and Composed |
| Composed | Route briefing |
GET/POST /v1/route-briefing
|
per part | minimum of parts | [[Weather, Rules and Composed |
| Composed | Place overview | GET /v1/places/{placeId}/overview |
per part | minimum of parts | [[Weather, Rules and Composed |
| Service | Sources, meta, health, description |
/v1/sources, /v1/meta, /healthz, /readyz, /v1/openapi.json, /docs
|
public | [[Service Endpoints |
GET /v1/places/{placeId} and GET /v1/road-situations/{situationId} extend the plan on API Design so that every id the API returns can be resolved again.
flowchart LR
I[Location input] --> A{Which form?}
A -->|at = lat,lon| P[Point]
A -->|place = id| R[Resolve place]
A -->|q = text| G[Gazetteer search]
G -->|one clear match| R
G -->|several| X[422 ambiguous-place<br/>with candidates]
G -->|none| N[404 not-found]
R --> P
P --> D{Inside coverage?}
D -->|no| O[422 outside-coverage]
D -->|yes| Area[Area: point and radius, box, or corridor]
| Parameter | Type and format | Default | Bounds | Meaning |
|---|---|---|---|---|
at |
lat,lon, decimal degrees |
lat −90..90, lon −180..180, ≤ 6 decimals | A point | |
place |
place id | A place from the place search | ||
q |
string, 1–120 characters | A free-text place | ||
radius_m |
integer | per operation (geo.default_radius_m, design 5 000) |
1 – geo.max_radius_m (design 50 000) |
Search radius around the point |
bbox |
min_lon,min_lat,max_lon,max_lat |
area ≤ geo.max_bbox_km2
|
A box instead of a radius | |
road, direction
|
road reference, enum north, east, south, west, both
|
both |
A motorway and direction | |
from, to
|
location (place id, lat,lon, or text) |
Section start and end on road, projected to the road |
||
from_km, to_km
|
number, one decimal | 0 – road length | Section by chainage instead of from/to
|
|
route |
encoded polyline (precision 5) | ≤ geo.max_route_points points, length ≤ geo.max_route_km
|
A client route | |
buffer_m |
integer |
geo.route_buffer_m (design 2 000) |
100 – 10 000 | Corridor half-width around a route |
| ID | Requirement | Verification |
|---|---|---|
| FR-LOC-001 | An operation that needs a location MUST accept exactly one of at, place or q. Zero or several of them is 400 (invalid-parameter). |
Handler |
| FR-LOC-002 | A q text MUST be resolved by the gazetteer. A single clear match MUST be used and reported in meta.query; several plausible matches MUST yield 422 (ambiguous-place) with at most places.max_candidates candidates (id, name, kind, region, location); no match MUST yield 404 (not-found). |
Handler |
| FR-LOC-003 | A point outside the coverage area (Germany plus a border margin of geo.coverage_margin_m) MUST yield 422 (outside-coverage). |
Unit |
| FR-LOC-004 | "Along" operations MUST accept either a motorway section (road with direction and from/to or from_km/to_km) or a client route with buffer_m; supplying both forms is 400. |
Handler |
| FR-LOC-005 | A route MUST be decoded with the standard polyline algorithm at precision 5 (latitude first) and MUST be refused with 400 when malformed, 422 (area-too-large) when it exceeds the point or length limit. Long routes SHOULD be sent with a query POST (PROT-012). |
Unit |
| FR-LOC-006 | Every area (radius, box, corridor) MUST be bounded by configuration; exceeding a bound is 422 (area-too-large) naming the limit. |
Config |
| FR-LOC-007 | The API MUST NOT compute routes. A route between places is the client's input; from/to only delimit a section of a named road. |
Review |
| Type | JSON shape | Notes |
|---|---|---|
GeoPoint |
{"lat": n, "lon": n} |
WGS 84, six decimals |
Money |
{"amount": "1.789", "currency": "EUR"} |
CONV-007 |
TimeWindow |
{"from", "fromLocal", "until", "untilLocal"} |
until null when open-ended |
Lamp |
enum green, amber, red, unknown
|
A summary computed by a documented, tested domain rule, identical to the MCP server's |
AdminRegion |
{"state": "DE-BY", "stateName", "district", "municipality"} |
Names in the response language where available |
Address |
{"street", "houseNumber", "postcode", "locality", "state"} |
Members null when not known |
OpeningState |
enum open, closed, unknown
|
Never a nullable boolean (CONV-012) |
Observed<T> |
{…, "observedAt", "observedAtLocal"} |
Any live state carries when it was observed |
| ID | Requirement | Verification |
|---|---|---|
| FR-GEN-001 | Each operation MUST declare in the OpenAPI document its scope, its source families, its cache family, its MCP counterpart where one exists, its default and maximum page size, its order, and at least one executed example. | Lint |
| FR-GEN-002 | For the same input and the same data, an operation with an MCP counterpart MUST answer the same facts (ids, names, positions to five decimals, prices, states, instants, families, note texts). | Parity |
| FR-GEN-003 | No path segment, parameter name or payload member MUST equal a storage name, except a short reviewed allow-list of generic words (id, name). |
Lint |
| FR-GEN-004 | Live states (availability, occupancy, prices, facility states, expected times) MUST carry their own observation instant. | Contract |
| FR-GEN-005 | Text fields from publishers (headlines, descriptions) MUST be returned as plain text, never HTML, with control characters removed; the language of each such text MUST be tagged when it differs from meta.language. |
Unit |
| FR-GEN-006 | An operation that is switched off by configuration (endpoints.disabled) MUST answer 404 (feature-disabled) and MUST disappear from the served OpenAPI document. |
Config |
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