ADR 0028: Reverse Lookup Precision Policy
Status: accepted Date: 2026-05-22
Context
Reverse place lookup can use precise coordinates, rounded coordinates, centroids, radii, bounding boxes, or spatial envelopes. Automatic album suggestions need useful place titles for clusters, but exact per-photo GPS coordinates are sensitive and often unnecessary for an album title. Even local cache/log/provenance rows should avoid more precision than the feature needs.
This decision must balance:
- title quality, especially for venues/toponyms;
- privacy and low surprise;
- inspectable provenance;
- provider-neutral lookup contracts;
- future optional external online providers, where precision disclosure is even more sensitive.
Options Considered
| Option | Summary | Benefits | Costs / Risks |
|---|---|---|---|
| A. Always exact coordinate lookup | Use raw media GPS or exact cluster centroid | Best possible local precision | Stores/logs/exposes more precision than needed; bad default for online providers |
| B. Always coarse area lookup | Only use broad rounded/envelope inputs | Strong privacy | Poor venue/toponym title quality |
| C. Privacy-first escalation | Start with cluster envelope or centroid+radius; store precision class; escalate to narrower local lookup only when needed and allowed | Balances privacy and title quality | More logic/provenance states |
| D. Provider decides precision | Let each provider adapter choose | Flexible | Fragmented privacy behavior; hard to reason about |
Decision
Use privacy-first precision escalation.
For automatic album title generation:
- Core should prefer a cluster-level spatial envelope, bounding box, or centroid plus radius instead of raw per-photo GPS points.
- Lookup requests and cached labels must record a
lookupPrecisionClass, such asenvelope,centroid_radius,rounded_coordinate,exact_coordinate, orfallback. - Album title lookup should start with
envelopeorcentroid_radiusprecision. - Core may perform a narrower local lookup, such as
rounded_coordinateorexact_coordinate, only when:- the feature needs a narrower
venue/localitycandidate; - the media owner is authorized for the underlying location metadata;
- the provider is local, or an external provider has explicit operator enablement and disclosure for that precision class;
- provenance records the precision class used.
- the feature needs a narrower
- External online providers must default to the least precise useful input and require explicit disclosure before any exact-coordinate lookup is allowed.
- Normal logs should avoid exact coordinates and should prefer precision classes, provider IDs, and coarse envelope identifiers unless debug mode is explicitly enabled.
For regional parent album titles, precision class is not the same as containment
evidence. A centroid_radius lookup can find nearby toponyms, but point-derived
synthetic buffers must not by themselves justify a narrow city/village title when
child/event anchors disagree. Regional title selection needs common hierarchy,
derived administrative coverage, validated geographic-area evidence, child-place
summary, or fallback.
This policy does not reduce Core's authoritative stored media coordinates. It governs reverse lookup requests, cached labels, provider calls, generated title provenance, and logs.
Consequences
Positive
- Avoids normalizing exact per-photo GPS disclosure for album titles.
- Keeps place title provenance honest about how precise the lookup was.
- Allows venue-level quality when local data and owner policy justify narrower lookup.
- Creates a clear additional disclosure boundary for external online providers.
Negative / Costs
- Requires precision-class modeling in requests/cache/provenance.
- Title generation may need multiple lookup passes or fallback behavior.
- Some venue labels may be missed if the policy stays at envelope precision.
- External providers need per-precision disclosure and possibly separate configuration.
Revisit Triggers
Revisit this decision if:
- Envelope/centroid lookup quality is too poor for automatic album titles.
- Users prefer exact local lookup and accept the local cache/provenance sensitivity.
- External online provider support requires stricter anonymization/proxying rules.
- PostGIS queries make precision classes too coarse to express actual lookup behavior.
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