ADR 0033: GeoNames Provider Mapping Validation Gate
Status: accepted Date: 2026-05-22
Context
ADR 0025 defines the normalized place hierarchy consumed by product features: venue, locality, city, geographic_area, admin_region, country, and fallback. GeoNames is the likely first local provider, but its feature classes/codes and data quality may not map cleanly to all levels, especially venue and geographic_area.
This cannot be resolved honestly by architecture alone. It needs empirical validation against sample GeoNames extracts and known family-memory title examples.
Options Considered
| Option | Summary | Benefits | Costs / Risks |
|---|---|---|---|
| A. Declare GeoNames sufficient | Assume mapping works for all ADR 0025 levels | Fast planning | False confidence; poor titles later |
| B. Drop weak levels now | Only support city/region/country from GeoNames | Honest and simple | Gives up on desired venue/geographic-area titles too early |
| C. Empirical mapping gate | Define candidate mapping, test sample extracts/examples, then decide supported levels | Honest, incremental, evidence-based | Requires validation work before production tasks |
| D. Switch to OSM/POI first | Use richer provider immediately | Better venue potential | Heavier data/import complexity before GeoNames is tested |
Decision
Use an empirical GeoNames mapping validation gate before production reverse lookup tasks.
The first implementation/research slice should:
- define an explicit candidate mapping from GeoNames feature classes/codes into ADR 0025 normalized levels;
- import a small fixture plus at least one real country/region extract relevant to Christian's expected data, e.g. Denmark and/or Germany;
- test known coordinates/envelopes for examples such as city, admin region, country, geographic area, and venue-like/title examples;
- measure whether GeoNames can support each normalized level with acceptable quality;
- mark levels as
supported,experimental, orunsupported_for_providerfor the GeoNames provider profile; - ensure automatic album title generation degrades gracefully when a requested level is unsupported and records capability provenance when a feature-specific title policy uses an experimental level.
Production tasks should not assume GeoNames provides good venue or geographic_area labels until this validation passes for those levels. City/admin-region/country may be implemented first if they validate earlier.
The selected next-step GeoNames scope is intentionally curated rather than
all feature codes. It includes A.ADM1 through A.ADM4 because those levels
belong to a real administrative hierarchy and can support common-ancestor title
selection. For these administrative levels, Memories may derive approximate
coverage polygons from descendant toponyms and sibling partitioning as
non-authoritative title-selection evidence. This derivation must not be applied
to non-administrative classes (P.*, L.*, T.*, H.*, S.*) because those
classes do not form a strict containment hierarchy.
GeoNames point-derived synthetic buffers are search aids, not proof that a label
honestly contains an album candidate. In particular, regional automatic album
titles must not use a centroid-nearest populated place such as Holzerath when
child/event anchors indicate a multi-place trip.
Capability flags have distinct meanings:
supported: feature code may use the level as a normal title candidate for the validated scope.experimental: feature code may use the level only when the feature-specific title policy accepts the quality tradeoff, records capability provenance, and avoids stronger precision claims.unsupported_for_provider: feature code must degrade to another level/provider/fallback.
Consequences
Positive
- Avoids false precision in automatic album titles.
- Keeps GeoNames as a practical first candidate without overpromising venue/toponym quality.
- Produces concrete provider-profile capability metadata that Admin/UI/title generation can use.
- Leaves room for future OSM/POI or user-authored labels for weak levels.
Negative / Costs
- Adds a validation slice before broad implementation tasks.
- May reveal that GeoNames is only good enough for city/region/country, requiring fallback or another provider for venues.
- Requires curated test coordinates/envelopes and expected title behavior.
Revisit Triggers
Revisit this decision if:
- GeoNames mapping proves obviously sufficient or insufficient and the provider profile can be simplified.
- Another local provider becomes the first implementation target.
- User-authored favorite places become the primary source for venue/locality labels.
Memories Wiki
Using Memories
- Accounts, the Library Hub, and Data Export
- Albums and Automatic Suggestions
- Explore and Discovery Domains
- The Media Viewer
- People and Faces
- Places and Map
- Plants (In Development)
- Datenschutzerklärung (Privacy Policy)
- Fast, Progressive Image Loading
- Search
- Sharing and Households
- Timeline and Photos
- Uploading and Import
Self-Hosting
- Backup and Restore
- CLI Password Reset
- Deployment Architecture
- Known Issues and Operator Diagnostics
- Map Tiles and Place Data Privacy
- Storage Layout
- Upgrades and Versioning
- Workers
Reference