Skip to content

Data Model Places

mavrovde edited this page Nov 1, 2026 · 1 revision

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.

1. Diagram

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
  }
Loading

2. Entities

admin_region

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

place

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

place_alias

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)

address

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

point_of_interest

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

3. Keys and relationships

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.

4. Temporal behaviour

  • All entities are reference records (REF): updated in place, soft-closed when withdrawn.
  • A withdrawn place keeps answering GET /v1/places/{placeId} for the life of its id; with a successor_id it redirects.
  • Addresses and points of interest have no history in the read model; only the current version is held.

5. Access paths

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

6. Licence and attribution

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

7. Entity to API

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.

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally