From b36103d2a940a62ac9c352e81702c2db654d79ef Mon Sep 17 00:00:00 2001 From: Maurice Date: Sun, 9 Aug 2026 22:32:01 +0200 Subject: [PATCH] Document where place pictures and descriptions come from NOTICE knew about geoBoundaries, OSM and OurAirports but not about Wikimedia, Wikipedia or Google Places, all of which TREK has been calling for a while. Also fixes two dead paths in the place contract - it still pointed at server/src/routes/places.ts and services/placeService.ts, both long gone. --- NOTICE.md | 26 ++++++++++++++++++++++++-- shared/src/place/place.schema.ts | 10 +++++----- wiki/Places-and-Search.md | 26 ++++++++++++++++++++++++++ 3 files changed, 55 insertions(+), 7 deletions(-) diff --git a/NOTICE.md b/NOTICE.md index 630a78f4d..03314d8c8 100644 --- a/NOTICE.md +++ b/NOTICE.md @@ -21,12 +21,34 @@ property names TREK consumes. Country borders (`admin0`) derive from the geoBoun CGAZ composite; sub-national regions (`admin1`) derive from the per-country open (gbOpen) release. -## OpenStreetMap — geocoding +## OpenStreetMap — geocoding, place details & descriptions -Atlas reverse-geocodes places via the **Nominatim** service. Geocoding data is +Atlas reverse-geocodes places via the **Nominatim** service, and place search, +details and descriptions come from Nominatim and **Overpass**. Data is © OpenStreetMap contributors, licensed under the Open Database License (ODbL). https://www.openstreetmap.org/copyright +## Wikimedia Commons & Wikipedia — place pictures & descriptions + +Pictures offered for a place come from **Wikimedia Commons** (geosearch by +coordinate) and are cached locally rather than hotlinked. Descriptions can come +from **Wikipedia**, resolved from the place's OpenStreetMap `wikipedia` tag. + +Commons files carry their own licence, most often **CC BY** or **CC BY-SA**. TREK +shows the author, the licence and a link to the file description page next to +every picture while it is being chosen, and keeps the author and licence with the +cached file so the credit stays visible afterwards. Wikipedia article text is +**CC BY-SA 4.0**. https://commons.wikimedia.org/wiki/Commons:Licensing + +## Google Places — optional place data + +When an administrator configures a Google Maps API key, place search, details, +pictures and editorial summaries can also come from the **Google Places API**, +subject to Google's terms. Photos carry the author attribution Google supplies +and no reusable licence; TREK displays that attribution and claims nothing +further. This path is off unless a key is configured, and each part of it has its +own switch in the admin panel. https://cloud.google.com/maps-platform/terms + ## OurAirports — airport reference data `server/assets/airports.json` is built from **OurAirports** diff --git a/shared/src/place/place.schema.ts b/shared/src/place/place.schema.ts index 23550c2fb..e2fe3fe7f 100644 --- a/shared/src/place/place.schema.ts +++ b/shared/src/place/place.schema.ts @@ -6,12 +6,12 @@ import { z } from 'zod'; * Place API contract — single source of truth for the /api/trips/:tripId/places * endpoints (place pool CRUD, GPX/map/list imports, image search, bulk delete). * - * Trip-scoped; mutations use the 'place_edit' permission. The legacy route - * (server/src/routes/places.ts) wraps placeService and fires the journey + * Trip-scoped; mutations use the 'place_edit' permission. + * server/src/nest/places/places.controller.ts fires the journey * place-created/updated/deleted hooks. Place rows are wide and provider-derived, * so create/update payloads stay mostly open with `name` pinned; string fields - * are capped (name 200, description 2000, address 500, notes 2000) by the legacy - * validateStringLengths, reproduced in the controller. + * are capped (name 200, description 2000, address 500, notes 2000) in the + * controller. */ const open = z.record(z.string(), z.unknown()); @@ -36,7 +36,7 @@ export type PlaceCategory = z.infer; /** * Full place entity as returned by the place list / get / create / update - * endpoints (server/src/services/placeService.ts -> getPlaceWithTags). All + * endpoints (server/src/nest/places/places.service.ts -> getPlaceWithTags). All * columns of the `places` table (see server/data DB) plus the joined `category` * projection and `tags` array. Numbers (lat/lng/price) are SQLite REAL, ids are * INTEGER; provider-derived columns are nullable. diff --git a/wiki/Places-and-Search.md b/wiki/Places-and-Search.md index d3c30f9b3..91f92885c 100644 --- a/wiki/Places-and-Search.md +++ b/wiki/Places-and-Search.md @@ -27,6 +27,32 @@ When a key is present, the autocomplete uses the Google Places API, which can re TREK falls back to OpenStreetMap (Nominatim) automatically — no API key needed. A notice appears above the search box explaining that OpenStreetMap is in use and that photos, ratings, and opening hours are unavailable. Results include name, address, and coordinates. +## Place details while searching + +On desktop the Place form carries a **Place details** column to the left of the form. Pick a search result and it fills in on its own — no extra click, and nothing changes about the usual add-a-place flow of searching, picking and saving. If you already know the place, ignore the column and save as before. + +The column shows: + +- **Pictures** near or of the place. Click one to make it that place's thumbnail; click it again to clear the choice. The picture then appears everywhere the place does — list, map marker, itinerary, PDF export and shared trips — exactly like a [custom place image](#custom-place-image). +- **A description**, when one is available. It is *not* written into the place automatically. Use **Use this text** to copy it into the description field; the button is disabled while you already have a description of your own, so nothing you wrote gets overwritten. + +Every picture is credited under its thumbnail with its author, its licence and a link to the source page. Most Wikimedia Commons pictures are CC BY or CC BY-SA, which means the credit has to travel with the picture — so once you pick one, the credit stays visible under the thumbnail in the place's detail panel too. + +### Where the information comes from + +Wikipedia and OpenStreetMap are always used and need no configuration: + +- Pictures from **Wikimedia Commons**, found by coordinate. +- Descriptions from the OpenStreetMap `description` tag, or from the Wikipedia article the place is tagged with. TREK resolves the article from that tag rather than guessing it from the name, so an ambiguous name never pulls in the wrong article. A place with no such tag simply gets no description. + +With a Google Maps API key, and only if the matching admin switches are on, up to three **Google Places** photos and Google's editorial summary are added on top. + +Pictures are copied to your own server and served from there — nothing is loaded directly from Google or Wikimedia while you browse, so no visitor's address leaves your instance. + +> **Admin:** the column is controlled by **Place Enrichment** in Admin → Settings → API Keys, and it is on by default. The Google half additionally follows **Place Photos** and **Place Details**. Turning Place Enrichment off leaves the column with a short note and makes no outbound calls. + +The column is desktop-only; the mobile place sheet is unchanged. + ## Pasting a Google Maps URL Paste a `maps.app.goo.gl/…`, `goo.gl/maps/…`, or `maps.google.*/…` URL directly into the search box and press the search button. TREK resolves it server-side and populates the name, address, and coordinates.