1 ADR 0022 reverse place lookup boundary
Forgejo Actions edited this page 2026-09-25 16:38:07 +00:00

ADR 0022: Reverse Place Lookup Boundary

Status: accepted Date: 2026-05-22

Context

Automatic album suggestions need human-readable place labels such as Landal Sonnenberg, Trier, Eifel, Rheinland-Pfalz, or Germany. Clustering can operate on stored coordinates and capture times, but useful titles require a reverse lookup from coordinates/spatial areas to place names.

This is not the same as map tiles:

  • Map tiles render a visual map for a viewport.
  • Reverse place lookup derives/caches textual place labels from coordinates or spatial areas.

Reverse lookup has privacy and operational implications. Coordinates often reveal homes, schools, vacations, medical visits, routines, and family relationships. Online reverse-geocoding providers can observe precise coordinates, request timing, IP address, API account, and usage patterns. At the same time, requiring users to manually name every place would make automatic albums much less useful.

GeoNames is a plausible first local-gazetteer candidate because its data extract can be downloaded as text files, country extracts are available, commercial use is allowed, and the data uses a Creative Commons Attribution license. GeoNames web services have request limits and would be an online provider, but the downloadable dump can support local lookup if imported/indexed by Memories.

However, GeoNames must not become the domain model. Memories should be able to replace or supplement it later with another provider source, such as an OSM-derived local POI extract, a country-specific dataset, user-authored favorite places, or an explicitly configured online provider.

Options Considered

Option Summary Benefits Costs / Risks
A. No reverse lookup Use only coordinates/fallback titles or owner-entered album names Maximum simplicity/privacy Automatic album titles are often weak; feature may feel unfinished
B. External online reverse geocoder Call Nominatim/GeoNames/Google/etc. for place names Good labels quickly; low local storage Privacy leak, terms/rate limits, cloud dependency, attribution complexity
C. Local downloadable gazetteer Import GeoNames or equivalent dataset into local index No online coordinate disclosure; self-hosted; good city/region/country labels Requires dataset download/import/storage/indexing, attribution, quality/version management
D. Hybrid provider boundary Prefer local/user/fallback sources; allow explicit opt-in online providers later Flexible and privacy-preserving by default More configuration/provenance complexity

Decision

Adopt a reverse place lookup provider boundary with a local-first default.

The target model is:

  1. Core API owns place-label lookup, caching, provenance, and policy.
  2. Automatic albums and other features ask Core for allowed place labels; they do not call providers directly.
  3. A local gazetteer/reverse-place index is the preferred way to get useful titles without online coordinate disclosure.
  4. GeoNames or equivalent downloadable datasets are candidate local sources, subject to attribution, storage, update, and quality evaluation.
  5. External online reverse-geocoding providers are optional, explicit opt-in provider profiles with privacy disclosure. They are not required for core album suggestion behavior.
  6. Reverse lookup results are derived/presentation metadata. They do not modify original media, embedded EXIF, authoritative coordinates, or owner location overrides.

Rules

  1. Core-owned boundary: Only Core performs reverse place lookup for product features. Web clients do not send coordinates directly to third-party place providers.
  2. Local-first provider order: User-authored labels and local gazetteer results are preferred over external online providers. Fallback approximate titles remain available when no place label exists.
  3. Provider-neutral contract: Product features consume normalized place-label candidates from Core, not provider-specific tables, IDs, feature classes, or hierarchy rules.
  4. Provider-specific provenance allowed: Cached labels may retain provider-native IDs/raw fields for audit/debug/export, but title/search/visibility logic must use normalized fields.
  5. Provider provenance: Every cached place label records provider/source, dataset/version, lookup precision, timestamp, language/name variant when known, and attribution requirements.
  6. Precision control: Lookups should support rounded coordinates, bounding boxes, or spatial envelopes where possible rather than always using precise raw GPS points.
  7. No authority transfer: Place labels are title/place candidates, not authoritative media coordinates or location overrides.
  8. Privacy policy applies: A user may see a place label only when they are authorized to see the underlying media/location metadata for the feature using it.
  9. Export/backup: Cached place labels, provider configuration, dataset identity, and title provenance must be included in fidelity backup and represented in inspectable export where relevant.
  10. Attribution: If GeoNames or another attributed dataset/provider is used, Memories must surface required attribution in product documentation or UI according to that source's license/terms.

Consequences

Positive

  • Automatic album titles can be useful without requiring online coordinate disclosure.
  • The same boundary can later serve Places, Map labels, search facets, and media-detail place display.
  • GeoNames can be used first without locking the architecture to GeoNames-specific semantics.
  • Provider provenance keeps generated titles inspectable and reversible.
  • External online providers remain possible for users who knowingly accept the privacy tradeoff.

Negative / Costs

  • Local gazetteer support adds storage, import, indexing, update, and attribution tasks.
  • Provider normalization adds design work because GeoNames, OSM-derived datasets, user labels, and online providers do not share exactly the same place hierarchy.
  • GeoNames quality may vary by country, toponym type, and feature class.
  • Venue/toponym precision such as Landal Sonnenberg may require richer datasets than basic city/country reverse lookup.
  • A provider abstraction is more work than directly calling an API.

Operational Impact

  • Operators may need a documented dataset download/import step or an optional packaged dataset volume.
  • Dataset version and update status should be visible in Admin.
  • Large worldwide datasets may be heavier than country/region extracts; deployment should support installing only relevant countries where practical.

Privacy Impact

  • Local gazetteer lookup avoids disclosing coordinates to a remote service.
  • External online providers, if enabled, can observe coordinates/areas, request timing, IP address, user agent/server identity, and API account. Memories must disclose this before enablement.
  • Cached labels may reveal sensitive locations and must follow the same visibility/export care as location-derived metadata.

Revisit Triggers

Revisit this decision if:

  • GeoNames licensing, attribution, quality, or data shape is unsuitable.
  • A better local gazetteer source becomes preferred.
  • Provider-neutral normalization proves too weak for title generation or search.
  • Memories needs precise venue/POI lookup beyond what local gazetteers provide.
  • External online lookup becomes common enough to need per-provider ADRs or proxy/anonymization rules.
  • Reverse lookup becomes authoritative for user-edited location metadata rather than only title/place suggestions.