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.
This commit is contained in:
Maurice
2026-08-09 22:32:01 +02:00
committed by Maurice
parent 5d99886b04
commit b36103d2a9
3 changed files with 55 additions and 7 deletions
+24 -2
View File
@@ -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**
+5 -5
View File
@@ -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<typeof placeCategorySchema>;
/**
* 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.
+26
View File
@@ -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.