Repository navigation
Data Model Places
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, Places.
Places resolve first for every other domain: a text, an id or a coordinate becomes a place or an area. The domain holds named places, the administrative regions they lie in, addresses and points of interest.
erDiagram
admin_region ||--o{ admin_region : "contains"
admin_region ||--o{ place : "contains"
place ||--o{ place_alias : "is called"
place |o--o| place : "is succeeded by"
admin_region ||--o{ address : "contains"
admin_region ||--o{ point_of_interest : "contains"
source ||--o{ place : "describes"
source ||--o{ address : "describes"
source ||--o{ point_of_interest : "describes"
admin_region {
string region_code PK
string region_level
string name
string parent_code FK
polygon boundary
}
place {
string place_id PK
string place_kind
string name
point location
polygon extent
string region_code FK
string official_key
int prominence
string successor_id FK
string source_ref FK
}
place_alias {
string place_id FK
string label
string lang
string name_kind
string search_fold
}
address {
string address_id PK
string street
string house_number
string postcode
string locality
string region_code FK
point location
string source_ref FK
}
point_of_interest {
string poi_id PK
string category
string name
point location
string opening_hours_text
string region_code FK
string source_ref FK
}
An administrative unit of Germany: a federal state, a district (Kreis or kreisfreie Stadt) or a municipality. Regions form a tree. Retention REF.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
region_code |
key |
yes | ISO 3166-2 for states (DE-BY); the official regional key for districts and municipalities |
unique | Identity of the region |
region.state, place filter state
|
region_level |
enum<region_level> |
yes |
state, district, municipality
|
Level in the tree | which member of AdminRegion it fills |
|
name |
ltext |
yes | Official name |
region.stateName, region.district, region.municipality
|
||
parent_code |
key → admin_region
|
no | null only for states | The enclosing region | used to fill AdminRegion
|
|
boundary |
polygon |
no | WGS 84 | valid polygon | Outline, where held | none; used for point-in-region |
A named place a person may ask about: a town, a district, a locality, a region, a state or the area around a station. Retention REF; a retired place keeps its id and may name a successor.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
place_id |
id |
yes | unique, stable | Identity |
id (pl_…) |
|
place_kind |
enum<place_kind> |
yes | see dictionary | What kind of place | kind |
|
name |
ltext |
yes | non-empty | Display name as published | name |
|
location |
point |
yes | WGS 84 | inside coverage | The one representative point every operation uses (FR-PLACE-003) | location |
extent |
polygon |
no | WGS 84 | Outline or envelope |
bbox (envelope of extent) |
|
region_code |
key → admin_region
|
no | Smallest enclosing region | region |
||
official_key |
key |
no | official municipal key, 8 or 12 digits | The statistical key of a municipality or district | none in v1 | |
prominence |
int |
yes | ≥ 0 | Search weight that breaks ties between equal names | relevance order only | |
successor_id |
id → place
|
no | not self | The place that replaced a retired one |
308 redirect (FR-PLACE-004) |
|
| envelope |
source_ref, origin_key, published_at, recorded_at, changed_at, withdrawn_at
|
sourceFamily |
No population or other statistic is part of the read model (FR-PLACE-008).
Every name a place can be found by: the official name, alternate and foreign-language names, and postcodes. Retention REF.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
place_id |
id → place
|
yes | Named place | none | ||
label |
text |
yes | non-empty | The name as written |
name when it matched and is in the response language |
|
lang |
text |
no | BCP 47 | null for postcodes | Language of the name |
meta.language choice |
name_kind |
enum<name_kind> |
yes |
official, alternate, exonym, postcode
|
Why this name exists | matchedOn |
|
search_fold |
text |
yes | lower case, diacritics folded | The search key (FR-PLACE-001) | none (storage-only) |
A postal address with its position. Addresses from share-alike sources stay in records of their own source (DM-012). Retention REF.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
address_id |
id |
yes | Identity |
id (ad_…) |
||
street |
text |
no | Street name as published | address.street |
||
house_number |
text |
no | House number as published, with suffix | address.houseNumber |
||
postcode |
text |
no | five digits | ^[0-9]{5}$ |
Postcode | address.postcode |
locality |
text |
no | Town or locality name | address.locality |
||
region_code |
key → admin_region
|
no | Enclosing region | address.state |
||
location |
point |
yes | WGS 84 | Position of the entrance or building | location |
|
street_fold, number_fold
|
text |
yes | folded | Search keys: street folded; house number lower-cased without spaces (FR-PLACE-006) | none (storage-only) | |
| envelope | sourceFamily |
A place of public interest a traveller may need: a hospital, a pharmacy, a police station, a rest area, a workshop, a toilet. Retention REF.
| Field | Type | Req | Unit / format | Constraints and values | Description | API field |
|---|---|---|---|---|---|---|
poi_id |
id |
yes | Identity |
id (poi_…) |
||
category |
enum<poi_category> |
yes | see dictionary | What it is | category |
|
name |
text |
no | Name as published | name |
||
location |
point |
yes | WGS 84 | Position |
location, distanceM
|
|
street, house_number, postcode, locality
|
text |
no | as in address
|
Address where published | address |
|
opening_hours_text |
text |
no | the publisher's opening-hours syntax | not interpreted | Opening hours as published | openingHours |
region_code |
key → admin_region
|
no | Enclosing region | none | ||
| envelope | sourceFamily |
| Relationship | Cardinality | Rule |
|---|---|---|
admin_region → parent |
many to one | A tree: state, then district, then municipality |
place → admin_region
|
many to zero-or-one | The smallest region that contains the place's location
|
place → place_alias
|
one to many | Every place has at least its official name |
place → successor place
|
zero-or-one to zero-or-one | Only on retired places |
address, point_of_interest → admin_region
|
many to zero-or-one | Derived from location
|
Every record → source
|
many to one | Record envelope |
Natural keys (origin_key) are unique within their source. The same town described by two sources is two records unless a documented matching rule merges them into one place.
- All entities are reference records (
REF): updated in place, soft-closed when withdrawn. - A withdrawn
placekeeps answeringGET /v1/places/{placeId}for the life of its id; with asuccessor_idit redirects. - Addresses and points of interest have no history in the read model; only the current version is held.
| Path | Used by |
|---|---|
Text search on place_alias.search_fold, ordered by match quality, then prominence, then distance to a bias point |
place search, q= resolution (FR-LOC-002) |
By key on place_id
|
get a place, place= resolution |
Point in admin_region.boundary
|
region of any result, describe a point |
Nearest address to a point within a configured distance |
describe a point |
| Folded street plus folded house number, optionally postcode or locality | address search |
Nearest point_of_interest by category within a radius |
points of interest |
Each record carries its source_ref. Address and point-of-interest records may come from a share-alike source; they keep that source on every record, are never combined with records of another licence, and every answer that uses them carries the share-alike flag and offer (LIC-005).
| Entity | Operations | Resource members |
|---|---|---|
place, place_alias, admin_region
|
GET /v1/places, GET /v1/places/{placeId}, every place=/q= input |
place item; meta.query
|
admin_region |
every located result | AdminRegion |
address |
GET /v1/addresses, GET /v1/locations/describe
|
address item, nearestAddress
|
point_of_interest |
GET /v1/points-of-interest |
point-of-interest item |
junction ([[Roads |
Data-Model-Roads]]) | GET /v1/locations/describe |
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