Locations¶
Purpose¶
The location stack converts a user's tap-on-the-map (or text query) into a persisted, enriched Location row. Every caller that needs a place — moments, events, voyages, waypoints, canonical-list ingestion — goes through this service. No duplicate location logic anywhere else in the system.
Every persisted Location is backed by a real Photon or Google Places match. When neither provider knows a place, no row is created and the caller is expected to keep the coords on its own row (moments and events both support this via their embedded Spatial). There is no manual placeholder row.
Three layers compose the service:
LocationService— the central manager for all place work. Owns the Photon-first provider policy, the dedup ladder, the Redis cache, the create path, and the sole calling surface for the enrichment transport (EnrichCapture).ProviderAdapter— common interface around external providers. Two implementations:photonAdapter(wrapsphoton.Service) andgoogleAdapter(wrapsplaces.Service). Handlers never see the underlying services.- Platform pieces —
platform/photon(self-hosted Photon/OSM geocoder) andplatform/places(Google Places, reached either through the cheap Serper transport or a direct billed call). The location service is the only consumer of both.
Code map — where things live¶
The domain is a single Go package (backend/internal/services/location/) plus per-aggregate sqlc packages. Methods on locationService must stay in that package; standalone concerns are split into their own files or subpackages.
| Concern | Files |
|---|---|
| Service orchestration | location_service.go (the LocationService interface + locationService), location_search.go (the searchCore pipeline), location_area.go, location_address.go, location_dedup.go, location_embedding.go |
| Ranking | ranking/ subpackage — the location adapter over the shared spine (internal/platform/ranking): the six-signal schema, weights, the LocationCandidate extractor, IPW harvest, and the durable label sink (RankingStore). The generic blend, text/geo primitives, metrics, and offline optimizer live in the spine. location_ranking_log.go (observability) and location_ranking_weights.go (config hot-refresh) stay in the domain package because they are locationService methods |
| Write / resolve / enrich | location_resolver.go, location_enricher.go, location_ingest.go, provider_adapter.go, place_signals.go |
| Capture-picker harvesting | harvest/ (ports, engine, governor, ledger), location_burst.go (the picker query, chips), harvest_wiring.go (sink, areas, worker handoff), location_harvest.go (admin area, type to category, quality gates, signals), location_search_more.go (the text lookup) |
| Localization | localization.go (fallback chain + trimming) |
| Persistence | location_store.go (locations + MergeInto), region_store.go (RegionStore → regiondb), country_store.go (CountryStore → countrydb), mappers.go |
| HTTP / wiring | handler.go, routes.go, wire.go |
Reference tables. regions (admin½/3) is read at runtime through region_store.go. countries is read through country_store.go (list + get). Both tables are populated by the catalog seeder (cmd/catalogseeder), not written at runtime.
Admin-area resolution. regions.boundary (a geometry(MultiPolygon,4326), GiST-indexed) carries the area's polygon; reads never SELECT it (pgx can't decode geometry), only ST_Contains in FindAdminAreasContainingPoint. LocationService.ResolveAdminArea(lat, lng) returns the AdminArea{City, Region, Country} a coordinate falls in (finest containing area is the city, admin-1 is the region), for off-grid content that has coords but no resolved place (see the moment off-grid path in moments). The boundary geometry is seeded by the catalog seeder's gazetteer; nothing writes it at runtime here.
Provider policy¶
Photon is primary. Google is only consulted in three explicit cases:
- Caller hint —
ResolveRequest.Provider == "google_places"(the user picked a Google-sourced place from some other surface, or the caller already has a Google Place ID). - Rich-detail enrichment after a Photon hit — once a row is persisted from a Photon match AND its tag set intersects the rich-detail buckets (the buckets flagged
rich_detail: trueinbackend/data/place_taxonomy.json:food,drinks,coffee,tea,nightlife,entertainment,music,culture,fitness,wellness,shopping,accommodation,health,travel), the background enrichment worker calls GoogleNearbySearchand merges hours and contact details into the row (no photos, see Place photos). The Photon(provider, provider_id)pair stays canonical; the Google Place ID lands insecondary_providers. Google's rating + rating count are intentionally NOT copied —Location.AverageRating/TotalRatingsare the Tomoda-only user aggregate maintained byLocationService.RecordRatingfrom the moment + check-in publish paths; mixing Google's signal in would silently desync over time. EscalateOnMissresolves —ResolveRequest.Escalationlets a caller declare its resolve derives from an explicit place share (a Maps link, page structured data). On a Photon miss the service escalates to the Places API: the place is fetched cheaply through the Serper transport first (same Google Place plus rich signals, no billed call), and only if that yields nothing does it fall to a direct billed Google lookup. A shared Maps link names a place that definitionally exists, so the escalation almost always lands. The capture parser is the onlyEscalateOnMisscaller today; coords-only creates (events, moments) stay Photon-only and fall back to their own off-grid fields. The service owns this decision — callers never issue their own second Resolve.
A caller that has already harvested a place through the Places API (the capture pipeline via EnrichCapture) passes it in with EscalateExternal, which mints from the supplied POI on a Photon miss without any fresh provider call.
Read paths (Nearby, Search, Autocomplete) never call Google. Text search runs DB-first: PGroonga matches the multilingual search_text (see Search & ranking) and Photon fills in only when the local catalog returns fewer than the caller's limit.
The rich-detail bucket list is owned by the shared taxonomy service (Discovery → Taxonomy vocabulary) and read at runtime via TaxonomyService.RichDetailTags(). Adding rich_detail: true to a bucket in backend/data/place_taxonomy.json is the only thing needed to widen the enrichment escalation.
Every provider call increments location_provider_calls_total{provider,reason} (Prometheus). Watch in Grafana to verify the policy is being honoured in production.
Why this matters
Self-hosted Photon has zero marginal cost; Google Places is billed per request. The escalation policy keeps the Google bill bounded while preserving rich metadata where it actually matters (restaurants, hotels, etc.). Flagging a tag as rich_detail directly increases Google spend — surface it intentionally.
This aligns with the existing ADR Photon as Google Places fallback.
Place identity¶
The same place id concept wears different names at different boundaries. The canonical vocabulary is the (provider, provider_id) pair on models.Location:
| Where | Field / name | Shape |
|---|---|---|
models.Location (canonical) |
Provider + ProviderID |
photon + "{osm_type}:{osm_id}" (e.g. N:12345), or google_places + a Google Place ID (ChIJ…) |
models.Location.SecondaryProviders |
jsonb array | Cross-provider ids for the same row (e.g. the Google Place ID on a Photon-canonical row) |
LocationCandidate (provider transport DTO) |
GooglePlaceID, OsmID + OsmType |
Wire-in names from the provider clients, mapped to ProviderID at create |
Serper /maps (PlacePOI) |
PlaceID (+ CID, FID) |
PlaceID is a Google Place ID; CID/FID are Google Maps-internal ids kept on the link's ItemLinkSignals, not on Location |
| Photon response | State |
Renamed to Spatial.Region at the create boundary (createFromPhoton) |
Rules of thumb: everything inside LocationService speaks Provider/ProviderID; the other names exist only at serialization boundaries and are mapped exactly once, at create time. A Google id is never a column of its own — it is either the canonical ProviderID or an entry in secondary_providers.
Provenance — Serper-minted rows and the upgrade budget¶
Location.Provenance records how a row's data was sourced, independent of its provider identity:
The full value set is the LocationProvenance enum in backend/internal/models/location.go:
| Provenance | Meaning |
|---|---|
provider_api |
Hydrated by the provider's own API (Photon reverse geo, Google Places details/nearby). EnrichmentAt stamped when complete. |
serper_maps |
Minted by ResolveExternalPlace from a Serper /maps POI. Sparse (name/address/coords only) until the enricher fills it. |
geonames_seed |
Batch-loaded from the GeoNames gazetteer (cities + administrative areas). |
unesco_seed |
Minted from the UNESCO open-data portal (World Heritage). Curated, so it earns an embedding. |
wikidata_seed |
Batch-loaded from Wikidata (the notable overlay, Michelin/50 Best backing). Curated, so it earns an embedding. |
natural_seed |
Batch-loaded from the natural-places collection (mountains, lakes, rivers, islands). Not curated: it embeds on prominence or engagement only, and a merge with a notable or prestige row upgrades it to that row's provenance. |
osm_seed |
Reserved for the batch OSM/Overpass ingester. |
harvested |
Machine-harvested rows no user has engaged with: burst-discovery POIs. The enricher never paid-enriches these (Photon gap-fill only). They show on every surface (search, autocomplete, pickers, map backfill) but rank below engaged and curated rows (see Source trust below). Promoted to promoted on the first moment or check-in at the place. |
promoted |
A formerly harvested row a user meaningfully engaged with (see Demand-driven promotion). It earns paid enrichment, an embedding, and a place on the search page. |
isHarvested(loc) (which gates paid enrichment off) checks harvested;
isCuratedProvenance(loc) (which qualifies a row for an embedding) checks
unesco_seed, wikidata_seed, and promoted; natural_seed is not curated.
The one enricher (EnrichLocation) is two-tier and provider-agnostic. Tier 1, Photon gap-fill (forward-geocode missing coords, reverse-geocode localizations), runs for every row. Tier 2, paid commercial enrichment (Serper /maps, then the Google Places API fallback under the global daily budget enrich:upgrade:google in Redis), fires only when the row is rich-detail (tagsAreRichDetail) and not a harvested backbone row (isHarvested) and not already commercially enriched (hasFreshGoogleFields), except that a photo_backfill run takes the Serper pass for a photo-less row regardless. So a capture-minted serper_maps row is enriched by category, the density backbone is Photon-only, and localization gap-fill runs for all rows. The semantic embedding is gated separately (see Embedding gate): high-value + engaged rows earn a vector, the cold long tail stays lexical + spatial + category-searchable.
Local seeding is Serper-free by default
The Tier 2 paid step is gated by config.Location.BackgroundPaidEnrichment (env ENRICH_BACKGROUND_PAID, default true). task dev sets it false so seeding the catalog locally with a real Serper key does not drain the background sweep through thousands of paid calls. Tier 1 Photon gap-fill, embeddings, and region_id still run locally. Only the background worker respects the flag: the interactive resolve escalation (location_resolver.go) and the capture path (EnrichCapture) call the Serper enricher directly, so devs can still test them locally.
Service surface¶
LocationService¶
The interface lives in backend/internal/services/location/location_service.go. The high-value methods:
type LocationService interface {
Nearby(ctx, lat, lng, radius float64, lang string) ([]LocationCandidate, error)
// NearbyPlaces is the capture picker's list (nearest first, optional chip)
// plus whether a harvest would add places; FillNearby runs that harvest.
NearbyPlaces(ctx, q NearbyQuery) ([]LocationCandidate, bool, error)
FillNearby(ctx, userID uuid.UUID, q NearbyQuery) ([]LocationCandidate, FillStatus, error)
// Search parses the query through the taxonomy vocabulary and runs the
// resulting {category, tags, free-text} predicates against the DB plus a
// Photon fallback. lang biases localized display only.
Search(ctx, query string, lat, lng float64, lang string) ([]LocationCandidate, error)
// SearchFiltered is the lower-level entry taking already-parsed filters.
SearchFiltered(ctx, query string, bias *GeoBias, filters SearchFilters, lang string) ([]LocationCandidate, error)
// kinds allowlists which LocationKind rows come back: "poi" (default when
// empty), "settlement" (cities/towns/suburbs), "address", "residential".
// Plan + event pickers pass ["poi","settlement"]; the map picker keeps cities.
Autocomplete(ctx, query string, p GeoPoint, limit int, lang string, kinds []LocationKind) ([]LocationCandidate, error)
// Resolve returns the canonical Location for a place: existing row, or a
// new one created from the first provider (Photon-first, Google when
// hinted) that knows it. Returns (nil, nil) when no provider does — the
// caller keeps coords on its own row; the /resolve endpoint returns 404.
Resolve(ctx, req ResolveRequest) (*models.Location, error)
// ResolveExternalPlace find-or-creates from a fully-described place (a
// Serper /maps POI) with no provider details round-trip.
ResolveExternalPlace(ctx, p ExternalPlace) (*models.Location, error)
// MatchKnown resolves free-form text to a Location already stored, by
// substring name match — the free fast-path before any provider call.
MatchKnown(ctx, text string) (*models.Location, bool)
Get(ctx, id uuid.UUID) (*models.Location, error)
GetMany(ctx, ids []uuid.UUID) (map[uuid.UUID]*models.Location, error)
ReverseGeocodeCity(ctx, lat, lng float64, lang string) (string, error)
ReportOutdated(ctx, locationID uuid.UUID) error
Merge(ctx, source, target uuid.UUID) (*models.Location, error)
RecordRating(ctx, locationID uuid.UUID, rating float64) error
}
type ResolveRequest struct {
Name string
Lat, Lng float64
Provider ProviderName // "" lets the service pick (Photon-first)
ProviderID string
Escalation EscalationPolicy // opt Google retry on a Photon miss (Maps shares)
Hint *LocationHint // optional: category, address, country code
}
Search is the taxonomy-aware entry the search endpoints call; SearchFiltered takes a pre-composed SearchFilters (categories, tags, city, country) for callers that parsed the query themselves.
ProviderAdapter¶
type ProviderAdapter interface {
Name() ProviderName
SearchText(ctx, query string, bias *GeoBias, lang string) ([]LocationCandidate, error)
DetailsByID(ctx, externalID string) (*LocationCandidate, error)
ReverseGeo(ctx, lat, lng float64, lang string) ([]LocationCandidate, error)
}
NewPhotonAdapter(svc photon.Service) and NewGoogleAdapter(svc places.Service) wrap the platform-piece clients. The Photon adapter's DetailsByID returns (nil, nil) because Photon doesn't have a fetch-by-id endpoint — the caller falls through to the spatial path.
HTTP endpoints¶
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/v1/locations/nearby |
JWT | DB + Photon nearby (lat, lng, optional radius up to 10 km, intent, q, limit up to 50, lang): places nearest first. Returns {results, fill_needed, intent_counts, intent?}. fill_needed is true when the capture picker's ring has never been harvested; intent_counts counts nearby places per chip; q that names a category ("coffee") resolves to that chip and comes back as intent (see Capture-picker harvesting). |
| POST | /api/v1/locations/nearby/fill |
JWT | Body {lat, lng, radius, intent?, page?, country_code?, explicit?}. explicit: true marks a chip tap or a widened ring: its first page draws on the explicit pool (no per-user daily cap); a missing flag is automatic. Harvests the ring's cell from Serper /maps inline when it is cold (radius capped at 500 m), then returns {results, status, intent_counts} with status one of filled, fresh, disabled, limited, deferred, exhausted, no_area. page > 1 pages a chip deeper. |
| POST | /api/v1/locations/search-more |
JWT | Body {q, scope?, lat?, lng?, country_code?, auto?, surface?} (q 2 to 100 chars, scope nearby default, area or global). One Serper /maps text lookup for a place the free search missed, minted inline and cached per (scope, area, text); see Paid fallback. Returns {results, status}. /nearby/search-more is the nearby alias. |
| POST | /api/v1/locations/search-more/picked |
JWT | Body {surface}; metrics only |
| GET | /api/v1/locations/nearby/autocomplete |
JWT | Typeahead over the unified search core (q, optional lat, lng, limit, lang, kinds, surface) and returns {results, fallback}, fallback being eligible or none. Omitting coords gives an unbiased/area-driven search; kinds=poi,settlement keeps settlements (default is POI-only) |
| GET | /api/v1/locations/reverse |
JWT | Reverse-geocode coords to a city via Photon (lat, lng, lang) |
| GET | /api/v1/locations/countries |
JWT | The country reference list, prominence-ordered, each name localized to lang |
| GET | /api/v1/locations/countries/{code} |
JWT | One country by ISO 3166-1 alpha-2 code, name localized to lang; 404 when unknown |
| POST | /api/v1/locations/resolve |
JWT | Resolve a LocationCandidate into a persisted Location; returns 404 when neither Photon nor Google knows the place. The one resolve endpoint (pickers call it with name + coords, callers with a full candidate pass provider ids for an exact match). Frontends call this before submitting a moment/event so the payload carries a concrete location_id |
| POST | /api/v1/locations/{id}/report-outdated |
JWT | User reports that a location's info is stale. Always returns 200 (the response intentionally hides whether a background refresh actually fires, suppressed by the 7-day EnrichmentAt guard). Logged as location_outdated_reported |
The main text-search bar and place pickers call GET /api/v1/discovery/search/locations (see Discovery), which is a thin adapter over the same location.Search core (rich SearchLocation shape with friend-visitors + detail). Saving a found place to the plan Stash is a plan write, POST /items/save-location (see Plans), not a location endpoint.
See Discovery → Taxonomy vocabulary for the search query parser. The same lang parameter that picks Photon's translation language picks the taxonomy locale, so a search bar typed in Japanese resolves Japanese category and tag labels through the same call. The handler resolves lang from ?lang= → Accept-Language → "en" via api.Lang.
Place photos¶
A place's photos are images we host. Product decision: they come from the Serper /maps thumbnail of the adopted place. Serper thumbnails are signed Google image URLs that load for a short while after the search and 403 later, so they are never stored as URLs: the image is downloaded the moment a Serper place is adopted and rehosted.
- Runtime.
attachSignals(every Serper adoption: capture resolves, the Serper escalation, background enrichment) callsrehostPlacePhoto. It skips a place that already has a photo of ours, downloads through the SSRF-safe client (5 s timeout, at most 4 downloads in flight per process), validates withplaces.FetchThumbnail(HTTP 200, at most 5 MB, sniffed as JPEG, PNG, GIF or WebP, decodable dimensions of at least 64 px), and uploads withassets.UploadContentHashedasplaces-images/<sha256>.<ext>. Identical bytes always land on the same key, and an existing key skips the upload. The key goes intolocations.photos(a JSON array). Any failure leaves the place without a photo and the client shows its category cover. - Catalog seeder.
catalogseeder enrichsaves the top/mapsresult's thumbnail into<seed dir>/place-photos/<sha256>.<ext>right after each fresh Serper call (cached responses carry the saved path) and records it asSeedPlace.photo. The loader validates the file, uploads it under the same content-hashed key and fillslocations.photoswhen the row has no photo yet. The prestige lists that resolve through the topbest Serper backfill get their photo from this enrich pass. - Read path. Search rows and the place detail list, in order: the geo cover (
cover_image_url), the curated thumbnail (thumbnail_url), thenlocations.photoskeys composed to public URLs withstorage.PublicURL(OwnPhotoURLs). Places API photo names and Google-hosted URLs are never stored and are filtered on read; the Places mapper does not request photos. - Backfill. Each run of
cron:location_enrich_sweepalso queues up to 2 already-enriched, rich-detail, non-bulk rows that have no photo and were last enriched over 30 days ago (ListMissingPhotoIDs, most saved and photographed first), capped at 100 a day byenrich:photo-backfill. They run asphoto_backfillenrichment, which takes the Serper pass even when the row's detail is fresh and never falls back to a Places call for it. The pass needsENRICH_BACKGROUND_PAIDon and draws from the same daily Serper/Places budget as other enrichment. Nothing needs to be run by hand. To fill photos faster for one place, report it outdated or re-capture it.
Write path — the ingest funnel¶
Every location write, seeded or runtime, flows through one funnel,
LocationService.Ingest (location_ingest.go), so seeds and runtime-minted rows
get identical treatment and the write paths cannot drift:
- Exact dedup — batched
location_providerslookup on the candidates' source refs (FindLocationsBySources); a re-seed (same provider ids) reconciles rather than duplicates. - Fuzzy dedup — for candidates flagged
FuzzyDedup(runtime + OSM POIs), fold a new row into an existing same-named one withinfuzzyDedupRadiusM(150 m, a flat window on the batch funnel). Two rows that carry different ids of the same Google provider (serperCID orgoogle_places) are different places and never fold, in the stored-row recall and within a batch. PGroonga name-similarity recalls the nearest same-name candidate; the Go-sidesameNameForMergegate is what stops two distinct nearby places that merely share a token from merging. The gazetteer bulk load leaves the flag off (unique ids; two distinct "Springfield"s must not merge). The interactiveResolveladder uses a per-category dedup radius instead (see Per-category dedup radius); the batch funnel is the flat window. - Reconcile or create — a hit runs
models.FillMissing(fill empty fields, union localizations/tags, max prominence, add new source refs); a miss is bulk-created viastore.CreateBatch(COPY, which fires thesearch_texttrigger so bulk rows are searchable exactly like single inserts).
Localizations cover the languages the production Photon index carries
(SupportedLocalizationLanguages, 28); gazetteer rows arrive already localized
from GeoNames, POIs fill from Photon. Enrichment (rich detail, embeddings) runs
async off the same rows, so the create step never blocks on it.
Seeding — how rows get into locations¶
Rows arrive two ways, both through Ingest: the runtime resolve path
(user-driven, one place at a time, provider-first via LocationService.Resolve)
and the batch catalog seeder (offline, bulk — countries, cities, curated
lists, with provenance geonames_seed / unesco_seed / wikidata_seed). See
Catalog seeding.
| Entry point | Trigger | Notes |
|---|---|---|
| Frontend autocomplete submit (the dominant path) | User picks a candidate in the moment/event publish flow → frontend holds the candidate locally → at submit time hits POST /locations/resolve with the candidate |
Pre-resolution gives the moment/event a concrete location_id to attach to. Frontend never resolves on the pick itself — that would persist rows for abandoned forms. |
Moment create handler (POST /moments) |
Defensive fallback inside the create handler — fires when LocationID is nil AND coords are present (map-pin moment, scripted client) |
Off-grid moments (Photon doesn't know the place) keep LocationID=nil and carry LocationLabel + their embedded Spatial instead. |
Event create handler (POST /events) |
Same defensive fallback shape as moments | Off-grid events use LocationLabel + the embedded Spatial.Address for a user-supplied street address. |
| Future: voyage waypoint create | Same pattern, not yet shipped | Will use the same Resolve ladder; off-grid waypoints stay on their own coords. |
Admin merge (POST /backstage/locations/merge) |
Folds a duplicate Location into a survivor | Doesn't create a row — repoints the loser's location_providers rows onto the survivor so either id resolves going forward. |
Reads (/nearby, /autocomplete, /search, /reverse) never persist; they merge DB results with live Photon results for display only. The one write on the picker path is POST /nearby/fill, below.
Capture-picker harvesting¶
The picker's paid harvest (fill, search more, the governor, the ledger, the worker
handoff and outbox, abuse limits, metrics) has its own page:
Capture-picker harvesting. Reads (/nearby, /autocomplete)
never persist; POST /nearby/fill and POST /search-more are the only
picker writes.
Background enrichment¶
Enrichment is event-driven, never periodic. Two triggers exist; both enqueue the same location:enrich Asynq task (on the low priority queue) with different reason values, and the worker LocationService.EnrichLocation branches on the reason.
Trigger 1: row creation (reason = new_location)¶
Fires once, in createFromPhoton immediately after a new Photon-rooted row is persisted. createFromGoogle does not enqueue — Google rows are fully enriched at create time inside the synchronous path via MapPlaceToLocation.
| Current provider | Worker action |
|---|---|
photon AND tags ∩ rich-detail set ≠ ∅ |
Search-enrichment first (Serper today, swappable via SearchEnricher). On match: merge rating / hours / website / menu / phone / thumbnail into Location.Signals JSONB + direct columns, rehost the thumbnail into photos (see Place photos), append the Google placeId to secondary_providers. On miss / disabled / budget-exceeded: fall through to Google Places NearbySearch + MapPlaceToLocation (existing path). Photon stays as the canonical (provider, provider_id). |
photon AND no rich-detail tags |
No-op — Photon already gave us what it has. |
google_places |
No-op — already enriched at create. |
The rich-detail bucket set comes from TaxonomyService.RichDetailTags() (any bucket flagged rich_detail: true in backend/data/place_taxonomy.json, today the 14 buckets food, drinks, coffee, tea, nightlife, entertainment, music, culture, fitness, wellness, shopping, accommodation, health, travel). See Discovery → Taxonomy vocabulary.
Serper enrichment gates (belt + suspenders — mis-anchoring is worse than not enriching):
- Coord gate: the returned Serper POI must be within 200m of the Photon row's coords. Farther than that = different physical place = refuse the merge.
- Confidence gate:
PlaceConfidence ≥ 0.6(deterministic-guard matches score 0 and are accepted based on the coord gate alone; LLM-selected matches must clear 0.6).
The write path is naturally bounded (Photon dedup collapses duplicate rows; the endpoint rate-limit caps request rate; enrichment fires once per new rich-detail row), so no explicit daily budget guard is needed — a runaway would have to defeat both dedup layers first.
Google-provided identifiers: whether the enrichment came via Serper or a direct Google Places call, the CID / placeId are Google-issued (Serper is a scraping proxy on Google Maps). Both paths write the same {Provider: "google_places", ProviderID: <placeId>} secondary-provider entry, so a future direct-Google lookup for the same place dedups naturally against the Photon row. The CID is stored separately as google_cid (a harvested POI carries both refs, so either id arrives first and still matches one row), and promotion refreshes a stale google_places id from the matched place. Harvested rows also record harvest_origin (serper_area, serper_text, serper_enrich), set from the spending trigger at create and kept through promotion.
Create-time signal persistence (ResolveExternalPlace)¶
The item-enrichment pipeline (itemService.enrichLink) already has a full Serper SearchEnrichment in hand when it resolves a link to a Location. Rather than throw the data away and let the async worker re-fetch, the item path calls LocationService.ResolveExternalPlace with ExternalPlace.Signals pre-filled. The resolver then:
- Deduplicates by primary + secondary provider ID (
findByProviderID). - Deduplicates by proximity + name similarity (
FindByNameSimilarity, gated bysameNameForMerge). - Photon-first: reverse-geo at the supplied coords. If a match passes the 200m coord gate, the row is created Photon-canonical with the Google
placeIdas a secondary and the signals attached viaattachSignals. - Fallback:
createFromGooglewhen Photon misses — row stays Google-canonical, signals still attached.
Either way, Location.EnrichmentAt = now() is stamped at create-time and the row is not enqueued for async enrichment. The 7-day suppression guard then no-ops any stray enrichment task that lands on this row.
Trigger 2: user report (reason = user_reported_outdated)¶
Fires when a user hits "Report outdated info" on the location detail view in the frontend. The endpoint POST /api/v1/locations/{id}/report-outdated always returns 200 — from the user's POV they're filing a report, not commanding a refresh. The actual provider re-fetch happens in the worker:
| Current provider | Worker action |
|---|---|
photon |
Re-pull Photon ReverseGeo at the row's coords and overwrite name / address / city / country / category / tags / localizations from the fresh node. Then, if rich-detail, re-run the Google enrichment to refresh hours / photos / ratings. |
google_places |
Re-fetch Google Places.Details by the row's place_id and re-run MapPlaceToLocation (refreshes hours / photos / ratings / business status). |
The row's (provider, provider_id) identity is preserved — refreshes never re-key a row, so existing event / moment / waypoint references stay valid. Photon misses leave the existing fields intact rather than blanking them.
Soft-close lifecycle (tombstone, never delete)¶
A report-outdated refresh can conclude that a place is gone. When it does, the row is soft-closed, not deleted: it drops out of every forward-facing search but stays in the DB so historical linkages (past check-ins, moments, events, saves, passport visits, all FK'd to location_id) keep resolving.
A location is in one of three states, tracked on the existing is_active + business_status columns plus a closed_at timestamp:
| State | is_active |
business_status |
closed_at |
In search? |
|---|---|---|---|---|
| Operational | true |
OPERATIONAL |
null | yes |
| Permanently closed | false |
CLOSED_PERMANENTLY |
set | no (kept for history) |
| Temporarily closed | true |
CLOSED_TEMPORARILY |
null | yes (badge only) |
deleted_at is a separate concern (removed / bad rows) and is untouched by this lifecycle.
The refresh (refreshFromProviders → applyLifecycle in location_enricher.go) decides the transition:
- Provider reports
CLOSED_PERMANENTLY(GooglebusinessStatus, or Serper'spermanentlyClosedflag on a Photon-canonical row) → authoritative close:is_active=false,business_status=CLOSED_PERMANENTLY, stampclosed_at. - Provider reports
CLOSED_TEMPORARILY→ keep it searchable, persist the status as a badge only. - Place is NOT FOUND by the provider → not trusted on its own (renames, transient provider gaps, and obscure places all produce false negatives). Instead bump a
not_found_countcorroboration counter; the row only soft-closes once the count reachesnotFoundCloseThreshold(2). Below the threshold it stays active. - Provider re-confirms operational on a later refresh → reversible: reactivate (
is_active=true), clearclosed_at, resetnot_found_count,business_status=OPERATIONAL.
Search exclusion is enforced in queries.sql: the forward-facing recall queries (lexical, fuzzy, nearby/browse, semantic) all carry AND is_active, so a closed row never surfaces. GetLocationByID / ListLocationsByIDs deliberately do not filter on is_active — a closed place must still be fetchable by id so deep links and historical references render it with its permanently-closed label.
The 7-day guard¶
Both triggers share a single suppression check: if EnrichmentAt is within enrichmentMinAge = 7 days, the worker no-ops before touching either provider. This is what makes "no rate limit needed" safe — a user can mash the report button forever, but at most one refresh per location per 7 days actually fires. Each refresh writes EnrichmentAt = now() on completion.
Other safety nets:
- Asynq
TaskIDdedupe — collapses concurrent enqueues for the same(location_id, reason)while a task is in flight. MapPlaceToLocationis shared between the create path and both refresh paths, so a row's shape is identical regardless of which trigger last wrote to it.
What enrichment doesn't do (yet)¶
- Canonical-list tags (UNESCO / Michelin / 50 Best) —
EnrichReasonCanonicalPublishis defined for use when the canonical-list ingester lands; the handler does nothing with it today. - Periodic sweeps — intentionally removed. There is no daily cron and no batched re-enrichment. If a row's data goes stale and no user reports it, it stays as it is. (The
not_found_countcorroboration counter is per-row and only advances on a report-outdated refresh, not a periodic scan.)
Data model¶
locations:
name,address,full_addresscategory(varchar(64)) — one canonical leaf frombackend/data/place_taxonomy.json(Cafe,Restaurant,Bar,Mountain,Hospital,Wat,Synagogue, …). A place IS one thing; multi-membership lives intags.tags(text[], GIN-indexed asidx_locations_tags) — open-ended bucket + facet tag set frombackend/data/place_taxonomy.json. Picks up the category's default tags at create time (e.g.Cafe→["food","coffee","tea"]); additional facets likevegan,outdoor-seating, or cuisine tags can be appended by users, admin tooling, or canonical-list ingestion.WHERE tags @> ARRAY['vegan']andtags && ARRAY['food','coffee']are both index-served.business_status(OPERATIONAL/CLOSED_PERMANENTLY/CLOSED_TEMPORARILY),coordinates(PostGIS geometry, GiST-indexed viaidx_locations_coordinates_geog)is_active(bool, indexed) — search visibility gate;falsefor a soft-closed (permanently closed) row.closed_at(timestamp, nullable) stamps the authoritative close;not_found_count(int) corroborates provider misses before closing. See the soft-close lifecycle.- Source refs — every external identity for the row lives one-row-per-ref in the
location_providerstable ((provider, provider_id), composite unique), not a column onlocations. A row carries the full set (photon{osm_type}:{osm_id},google_placesPlace ID,wikidataQID,geonamesgeonameid,unescoid, …); there is no primary.models.Location.Sourcesis the in-memory view;findByProviderIDresolves a place by any of its refs (the merge cross-link path folds a loser's refs onto the survivor). provenance: theLocationProvenanceenum above; gates paid enrichment (isHarvested) and embedding (isCuratedProvenance).enrichment_at(timestamp, nullable) — last time enrichment ran; the 7-day guard reads it.search_text(text, PGroonga-indexed asidx_locations_search_text_pgroongawithNormalizerNFKC150) — the trigger-maintained lexical blob: base name + every localized name/city/country + address + admin area + neighborhood + tags, lowercased and accent-folded. Maintained by thelocations_search_text_synctrigger on every write that touches a searchable field, so bulk COPY inserts stay searchable exactly like single inserts.embedding(halfvec(1024), nullable) — the Qwen3-Embedding-0.6B semantic vector, populated async by the equalizer only for rowsshouldEmbedpasses. The ANN index (idx_locations_embedding_hnsw) covers its first 512 components; see Vector index.city_id(uuid self-FK, nullable) — the row's containing city (cities are locations); assigned in one set-based nearest-city pass at load. The per-city highlight promotion and localized-city read paths follow it.region_id(uuid FK →regions, nullable) — the containing administrative area; resolved by enrichment.localizations(JSONB, 28 languages),photos(JSON array ofplaces-images/keys, see Place photos),opening_hours,place_typesphone_number,international_phone_number,website,google_maps_uriaverage_rating,total_ratings,price_level,last_activity_at,deleted_at- Geographic denorm (on the embedded
Spatialstruct, shared with Events + Moments):district— sub-city neighborhood / suburb / borough; best-effort (Photon's OSM tags vary by country; Google fills it fromsublocality)city— populated by Photon'scityor Googlelocalitycomponentregion— state / province / prefecture; nullable for city-states (Singapore, Monaco, Vatican). Populated by Photon'sstateor Googleadministrative_area_level_1country,country_code— ISO 3166-1 alpha-2continent, derived at write time fromcountry_codeviageo.ContinentForCountryCode(backend/internal/geo/continents.go); one ofAfrica | Asia | Europe | North America | Oceania | South America | Antarctica- The Google path consults
addressComponentswhen available (structured, language-stable) and falls back toFormattedAddressparsing otherwise.
The denorm columns above are the display fast-path. The relational area tree lives in a dedicated regions table (region_store.go, regiondb/): one row per administrative area, with admin_level (1 = ADM1 state/province, 2 = ADM2 county/district, 3 = ADM3 where a country models it), a self-referential parent_region_id, coordinates, population, 28-language localizations, and the GeoNames feature_code + admin1_code/admin2_code that reconstruct the parent linkage. The seed loader resolves parents in level order (ADM1 before ADM2 before ADM3) via (country_code, admin1_code, admin2_code), index-served by idx_regions_admin_codes. A location's region_id FK points into this tree for grouping and for gazetteer recentering, separate from the flat region string denorm used for display.
Caching¶
| Cache | Key | TTL | Purpose |
|---|---|---|---|
| Provider-id resolve | location:provider:{provider}:{provider_id} |
1 h | Skip the DB lookup on hot paths (same place referenced by many users in quick succession) |
| Per-user Google rate limit | places:ratelimit:{userID} |
1 min | Existing — caps a user at 10 Google calls/min |
Admin merges don't actively invalidate today; the 1 h TTL is the upper bound on inconsistency. Explicit invalidation lands with the merge handler.
Dependencies¶
LocationStore(location_store.go), the domain's persistence port:CreateBatch,GetByID,Update,FindLocationsBySources,SearchLexical,SearchLexicalFuzzy,SearchSemantic,FindByNameSimilarity,PromoteHarvested,TopCityHighlightCandidates,UpdateEmbedding,MergeInto,VerifyMergeCoverageregion_store.go(region_store.go,regiondb/), the ADM1/ADM2 administrative-area store the seed loader and enrichment resolve againstplatform/cacheRedis abstraction:GetCache/SetCachefor the provider-id cache and the query-vector cache,RateLimitfor the Google rate limitplatform/photongeocoder client andplatform/placesPlaces client (Serper transport + direct Google), the two provider platform piecesplatform/placesSearchEnricher, the optional enrichment transport. The location service is its sole caller (viaEnrichCaptureand the async enrichment worker); capture pipelines delegate here rather than calling it directlyplatform/embeddings, the TEI (Qwen3-Embedding-0.6B) client the equalizer embeds rows and search queries throughplatform/taxonomy, the canonical place vocabulary, rich-detail set, and dedup radii- observability:
NewCounterVecforlocation_provider_calls_total, every(provider, reason)pair zero-initialised fromproviderCallReasons
Notable behavior¶
Photon-first, Google sparingly
Photon is queried for every read path with no rate limit. A direct billed Google call happens only when the caller explicitly hints Provider = ProviderGoogle or when a Places escalation exhausts the cheap Serper transport first. All other rich-detail enrichment runs in the background worker so the sync p95 stays bounded. The location_provider_calls_total{provider,reason} Prometheus counter exposes both sync and async escalations.
Localizations are universal across write paths
Every persisted location carries name translations, from every write path,
via free self-hosted Photon (buildLocalizations, a parallel reverse-geocode
across the supported languages — wall-clock cost is one Photon RTT):
Photon-resolved rows at create, Google-escalated rows at create,
Serper-minted sparse rows via the background enrichment worker, and batch-seeded
rows from their source data (Photon as an optional gap-filler). Serper and Google
are not localization sources — Photon is. On every read path the response is
trimmed to the caller's BCP 47 fallback chain via FilterLocalizationsForLang
(~90 % size reduction). Timezone is not stored — it is derived from coordinates (Timezones).
Photon never returns errors
photon.Service's doRequest and ReverseGeocodeCity deliberately swallow all errors and return empty slices/strings. Photon outages must not break user flows — the caller falls through to the off-grid path (no location_id, coords on the moment/event row).
Off-grid moments and events
Moments and events that resolve to nothing in Photon (private parties, pop-ups, unmapped spots) keep their coords on their own embedded Spatial rather than spawning a placeholder Location row.
Both also carry a location_label for the human-readable name in that case. Events additionally use the embedded Spatial.Address for a user-supplied street address — events typically have a place a guest needs to physically find, and "Park Avenue Backyard Party" without an address isn't useful.
Moments don't need an address — the coords are the address. The label is just for display ("Joe's Cabin", "Hidden Beach"), captured when the moment-create flow surfaces a prompt after the nearby lookup returns nothing.
Where to look¶
backend/internal/services/location/location_service.go: orchestrator,LocationServiceinterface, provider policy, cache,EnrichCapture,PromoteCityHighlightsbackend/internal/services/location/location_resolver.go: theResolveladder, escalation policy,createFromPhoton/createFromGoogle,ResolveExternalPlace, the allowlist gatebackend/internal/services/location/location_enricher.go:EnrichLocation(the two-tier enricher), soft-close (refreshFromProviders/applyLifecycle),buildLocalizations/gapFillLocalizations,PromoteOnEngagementbackend/internal/services/location/location_ingest.go: the single write funnel (Ingest, exact + fuzzy dedup,reconcileInto)backend/internal/services/location/provider_adapter.go:ProviderAdapterinterface + Photon/Google wrappersbackend/internal/platform/photon/photon_service.go,photon_osm_mapping.go: Photon HTTP client + language normalization;mapOsmCategoryproduces(canonical, tags)from OSM key/value + extrasbackend/internal/platform/places/places_service.go: Google Places v1 client +MapPlaceToLocation;search_enrichment.go+semantic_resolver.go: the Serper/mapstransport and the LLM place-selection gatebackend/internal/platform/embeddings/embeddings.go: the TEI client (Qwen3-Embedding-0.6B, halfvec) the equalizer embeds throughbackend/internal/services/location/handler.go,routes.go: HTTP surface (/locations/*)backend/internal/services/location/location_search.go,location_area.go,location_embedding.go,location_ranking.go: the unified search core, area-from-query detection, theshouldEmbedgate +embedRow, and the composite rankerbackend/internal/services/location/location_ranking_eval.go,testdata/ranking_golden.json: golden-set loader + NDCG/MRR eval + coordinate-ascent optimizer (over any labeled set), and the labelled cases they run onbackend/internal/services/location/location_ranking_harvest.go: harvests the durable label sink into inverse-propensity-weighted cases, and the guardrailed retune decision (held-out lift, golden-set regression floor, min-labels gate). Pure over[]models.RankingLabeledCase, no DBbackend/internal/services/location/location_ranking_log.go: search + selection ranking observability (the training-data logs)backend/cmd/rankertune: offline weight optimizer; default mode tunes the golden set,-harvestmode runs the guardrailed traffic retunebackend/internal/services/location/location_store.go,locationdb/queries.sql,region_store.go: Postgres queries,locationFKRewrites,MergeInto, the semantic query, theregionsstorebackend/cmd/catalogseeder: the batch seed pipeline (see Catalog seeding)backend/internal/platform/taxonomy/: canonical vocabulary, rich-detail set,ResolveQuery/ParseQuery,go:embedofbackend/data. See Discovery → Taxonomy vocabularybackend/internal/geo/continents.go,country_codes.go: continent + country-code helpersbackend/internal/models/location.go,spatial.go: schema- DevOps: the Photon planet index build pipeline (see devops)