wiki: sharing place details with the TREK Places API

What is sent and when, what never is, how values are checked before anyone sees them, and where an admin switches it off or takes it back. The new TREK_PLACES_CONTRIBUTE variable is listed with the compose file and the chart.
2026-11-13 07:40:59 +00:00 · 2026-10-30 18:15:37 +01:00
parent 013aa3954d
commit 18dc121132
6 changed files with 32 additions and 0 deletions
@@ -112,6 +112,9 @@ data:
  {{- if .Values.env.TREK_PLACES_URL }}
  TREK_PLACES_URL: {{ .Values.env.TREK_PLACES_URL | quote }}
  {{- end }}
+  {{- if .Values.env.TREK_PLACES_CONTRIBUTE }}
+  TREK_PLACES_CONTRIBUTE: {{ .Values.env.TREK_PLACES_CONTRIBUTE | quote }}
+  {{- end }}
  {{- if .Values.env.TREK_SERVICES }}
  TREK_SERVICES: {{ .Values.env.TREK_SERVICES | quote }}
  {{- end }}
@@ -113,6 +113,10 @@ env:
  # Base URL of a copy of the Places API you run yourself; it has to answer the same /v1 API. Read from
  # configuration rather than typed by a user, so an in-cluster address works without ALLOW_INTERNAL_NETWORK.
  # Defaults to https://places.liketrek.com.
+  # TREK_PLACES_CONTRIBUTE: "off"
+  # Whether an admin may let this installation send the place details its users typed in (website, phone, e-mail,
+  # opening hours, description, picture) to the TREK Places API. "admin" leaves the choice to the admin panel, where
+  # it stays off until an admin agrees; "off" takes it away. Defaults to admin.
  # TREK_SERVICES: "off"
  # Places search identifies this installation with a key it registers by itself on first use and keeps in the
  # database. "off" sends no key; searches then use the shared pool. A key issued to you goes under
@@ -61,6 +61,7 @@ services:
 #      - UNSPLASH_ACCESS_KEY= # Optional. Unsplash Access Key for trip-cover / place-image search. Without one, TREK uses Unsplash's unauthenticated endpoint, which some datacenter/VPS IPs are blocked from (#1449). Free key at unsplash.com/developers. Can also be set per-admin in Admin > Settings; the env var overrides that.
 #      - TREK_PLACES_ENABLED=false # Optional. Place search (suggestions, full search, category buttons, Road trip search, import geocoding, offline downloads, and the OpenStreetMap ways and horse routes Tours reads) asks the TREK Places API at https://places.liketrek.com by default, so the server makes outbound requests to that host. Set false to search the way it did before 4.3.0 (OpenStreetMap, or your Google/Amap key) and send nothing there. No switch in the admin panel on purpose: whether searches leave the instance is decided here. (default: true)
 #      - TREK_PLACES_URL=https://places.liketrek.com # Optional. Base URL of a copy of the Places API you run yourself; it has to answer the same /v1 API. Read from configuration rather than typed by a user, so an address on your LAN or Docker network works without ALLOW_INTERNAL_NETWORK. (default: https://places.liketrek.com)
+#      - TREK_PLACES_CONTRIBUTE=admin # Optional. Whether an admin may let this installation send the place details its users typed in (website, phone, e-mail, opening hours, description, picture) to the TREK Places API, so every installation gets better details. admin leaves the choice to the admin panel, where it stays off until an admin agrees; off takes it away and nothing is ever sent. (default: admin)
 #      - TREK_SERVICES=off # Optional. Places search identifies this installation with a key it registers by itself on first use. off sends no key; searches then use the shared pool. (default: auto)
 #      - TREK_SERVICES_KEY= # Optional. A key issued for this installation; it wins over the stored one and turns self-registration off.
 #      - TREK_PHOTON_URL=https://photon.liketrek.com # Optional. The address search of the TREK services. With a key, search and reverse lookups ask it before Nominatim and fall back to Nominatim when it does not answer; never asked when NOMINATIM_URL is set. (default: https://photon.liketrek.com)
@@ -76,6 +76,10 @@ Where place data comes from. The TREK index needs no key; the providers below it

 The first block, marked **Recommended default**. It is TREK's own place index: search without a Google key, without a quota and without anyone counting your lookups. There is nothing to configure here. The fold **What is in it** lists the fields a result carries (**Included**), what it does not have (**Not included**: ratings and photos of ordinary businesses) and its **Sources** (Overture Maps Foundation, OpenStreetMap, Wikivoyage, Wikimedia). See [TREK-Places-API](TREK-Places-API).

+#### Share place details
+
+Inside the TREK Places API block. One switch turns sharing on for the whole installation, one per field (website, phone, e-mail, opening hours, description, photo) chooses what goes along. The figures show the values accepted in the last 30 days, the ones waiting to be sent and the day of the last accepted one. The fold **Transmission log** lists every value sent with its result, and **Withdraw everything sent** takes all of it back out of the index. The first visit of an admin opens a dialog that asks once; nothing is sent before **Agree and share**. See [Sharing place details](TREK-Places-API#sharing-place-details).
+
 ### Google Maps API Key

 Optional. Without a Google key the TREK API is used. With one, photos, ratings and opening hours can be loaded on top, and every such lookup goes to Google. Create a key at console.cloud.google.com.
@@ -392,6 +392,7 @@ TREK's own place index, the [TREK Places API](TREK-Places-API), answers the sugg
 |-----------------------|-------------|---------|
 | `TREK_PLACES_ENABLED` | Set to `false` to stop asking the index. Search then works as it did before 4.3.0: OpenStreetMap on an install without a key, the keyed provider (Google or Amap) when one is set, the Overpass mirrors for the category buttons and for the OpenStreetMap ways and horse routes Tours reads, and no places downloaded for offline search. It is a boolean switch like the others on this page: `false`, `0`, `off` and `no` in any casing switch it off, a value that is not boolean-like aborts startup, and unset or blank leaves the index on. | on |
 | `TREK_PLACES_URL`     | Base URL of a copy of the service you run yourself; it has to answer the same `/v1` API. Unset or blank uses the public service. A trailing slash is stripped, and a value that is not a full URL aborts startup. It is configuration rather than user input and is not run through the SSRF guard, so an address on your LAN or Docker network works without `ALLOW_INTERNAL_NETWORK`. | `https://places.liketrek.com` |
+| `TREK_PLACES_CONTRIBUTE` | Whether an admin may let this installation send the place details its users typed in (website, phone, e-mail, opening hours, description, picture) to the TREK Places API. `admin` leaves the choice to **Admin > Settings**, where it stays off until an admin agrees; `off` takes the choice away and nothing is sent. Values the assistant, a plugin, an import or a provider filled in are never sent, and neither is anything from a development, test or demo instance, one with its own `TREK_PLACES_URL`, or one with `TREK_SERVICES=off`. | `admin` |
 | `TREK_SERVICES`       | `auto` lets the installation register itself with the TREK services on first use and keep its key in the database; `off` sends no key, and searches use the shared pool. See [Installation key and daily allowance](TREK-Places-API#installation-key-and-daily-allowance). | `auto` |
 | `TREK_SERVICES_KEY`   | A key issued to you for this installation. Wins over the stored key and turns self-registration off. A value that is not a key aborts startup. | none |
 | `TREK_SERVICES_HOSTS` | Comma-separated hosts that receive the installation key over https. | `places.liketrek.com,photon.liketrek.com,valhalla.liketrek.com` |
@@ -125,6 +125,7 @@ Every request goes out from your TREK server, never from a browser, so the servi
 | An `X-TREK-Instance` header | Every request |
 | A `User-Agent` of `TREK/<version>` | Every request |
 | The installation key as an `Authorization` header | Every request to a host in `TREK_SERVICES_HOSTS`, once the installation has one |
+| Place details your users typed: website, phone, e-mail, opening hours, description, picture, with the place's index or OpenStreetMap id | Only after an admin agreed under **Admin > Settings**, and only the fields switched on there. See [Sharing place details](#sharing-place-details). |

 The header carries an opaque token derived from your instance's own address, so the service can rate-limit each instance on its own instead of everyone behind one IP. Set `APP_URL` (or `ALLOWED_ORIGINS`): without either, the token is derived from the port alone, and two unconfigured installs on the same port share one rate-limit bucket.

@@ -134,6 +135,24 @@ The requests use Node's default HTTP client, so an outbound proxy set with `HTTP

 The instance's own [Place Search Log](Places-and-Search#place-search-log) is a different thing: it is off by default, lives in your database and never leaves the instance.

+## Sharing place details
+
+An installation can give back what its users add. When someone types a website, a phone number, an e-mail address, opening hours or a description for a place the index knows, TREK can send that value to the TREK Places API. After a check it is served to every installation, and this one gets what the others added in return.
+
+It is **off until an admin agrees**. The first time an admin opens **Admin > Settings** on an installation that can share, TREK asks once, with every field switched on. **Agree and share** turns it on with the switches as shown; **Not now** asks that admin again in 14 days; **No, thanks** keeps the question away until the terms change. Closing the dialog decides nothing. Users are not asked: the admin decides for the whole installation.
+
+What is sent:
+
+- Only values a user typed. A value Google or another provider filled in, one the assistant, a plugin or an import wrote, and a picture made from a trip file are never sent.
+- Only for places with an index or OpenStreetMap id. A place without one stays local.
+- The place's id, the field and the value. No user, account, trip, day, note or file goes along.
+
+What happens to it: a value for a field the index has no value for yet is published after automatic checks (format, country of a phone number, links). A value that would replace an existing one, every description and every picture wait for a review first. A picture is re-encoded on your server before it is sent: at most 2048 px on the long edge and one megabyte, with its metadata (the position it was taken at, the camera) removed. The index keeps up to eight pictures per place. Pictures stay off until their review is ready.
+
+Under **Admin > Settings > TREK Places API > Share place details** an admin can switch single fields off, see the figures of the last 30 days and the **Transmission log** (every value sent, with what the service made of it), stop sharing, and **Withdraw everything sent**, which removes every value this installation contributed from the index.
+
+An installation never sends anything when it is not in production, is a demo, uses its own `TREK_PLACES_URL`, runs with `TREK_SERVICES=off` or has `TREK_PLACES_CONTRIBUTE=off` (see [Environment Variables](Environment-Variables)).
+
 ## Switching it off

 ```yaml