k1nq/TREK
1
0
Fork 0
mirror of https://github.com/mauriceboe/TREK.git synced 2026-10-23 07:26:30 +00:00
Code Issues Packages Projects Releases Wiki Activity

feat(map): amap as map api provider and display template

Browse Source
This commit is contained in:
A1phaN
2026-09-07 10:04:12 +08:00
committed by Maurice
parent a066c94ec5
commit 57eac32f9f
92 changed files with 2910 additions and 70 deletions
Download Patch File Download Diff File Expand all files Collapse all files
wiki/Environment-Variables.md
+37
View File
@@ -314,6 +314,43 @@ To get a key: create a free account at [unsplash.com/developers](https://unsplas
---
## Place Search (Amap / 高德地图)
Google Places is unreachable from most networks inside mainland China, and OpenStreetMap's coverage of Chinese POIs —
restaurants, shops, the things a trip is actually made of — is thin and rarely in Chinese. TREK can use
[Amap (高德地图)](https://lbs.amap.com/) instead, as a first-class place provider: search, autocomplete, place details
and reverse geocoding all go through it, and there is an Amap basemap to match (see [[Map Settings|Map-Settings]]).
| Variable | Description | Default |
|-------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------|
| `AMAP_API_KEY` | Amap **Web 服务** (web service) key. When set, it takes priority over any key configured in **Admin → Settings → API Keys**, exactly like `PLACES_API_KEY` does for Google. | unset |
| `AMAP_API_SECRET` | The private secret (数字签名) of that key. **Required if — and only if** the key was created with signing enabled: such a key rejects every unsigned request. Leave unset otherwise. | unset |
| `AMAP_API_BASE` | Send the calls somewhere other than `https://restapi.amap.com` — an egress proxy, a cache, a gateway that holds the credential. The replacement has to speak the same API. Mirrors `PLACES_API_BASE`. | `https://restapi.amap.com` |
**Get a key** at [console.amap.com](https://console.amap.com/dev/key/app): create an application, then add a key of
type **Web 服务**. A **Web 端 (JS API)** key is a different kind of credential and will be rejected with
`INVALID_USER_KEY` — this is the single most common misconfiguration.
**Two ways to configure it** — pick one; the env var wins if both are present:
1. **Environment variable** (this page) — instance-wide, ideal for Docker/Helm where you already manage config as env.
2. **Admin → Settings → API Keys** — paste it into the **高德地图 API Key** field. Stored encrypted at rest.
Setting a key is not enough on its own: **Admin → Settings → API Keys → Place search provider** decides which provider
answers. `Automatic`, the default, keeps Google when a Google key is configured, then falls back to Amap, then to
OpenStreetMap — so adding an Amap key never silently moves an existing install off Google. Choose **Amap** explicitly
to make it the provider.
### Coordinates
Amap speaks **GCJ-02**, the offset datum Chinese law requires published maps to use; everything TREK stores is
**WGS-84**. The conversion happens at the boundary, in both directions, so what lands in the database, in a GPX export
or on a map is always WGS-84 — a place added through Amap and opened in OpenStreetMap later is in the right spot. You
do not need to configure anything for this, but it is worth knowing if you compare raw coordinates against Amap's own
website, which will differ by a few hundred metres.
---
## Storage & Paths
Storage backends and category assignment are configured in
wiki/Map-Settings.md
+20
View File
@@ -69,6 +69,26 @@ OpenFreeMap instead of drawing watermarked tiles. Save a key and your template i
Offline pre-download works on OpenFreeMap and on CARTO. It does not work on the OpenStreetMap presets, whose tile
servers do not permit bulk downloading.
## Amap (高德地图) basemap
Two presets — **高德地图 (Amap)** for the road map and **高德卫星 (Amap Satellite)** for imagery. They need no key and
no account, and inside mainland China they are far better than anything else in the list: OpenStreetMap and
OpenFreeMap are sparse there, and the foreign tile CDNs are slow or unreachable.
These tiles are drawn in **GCJ-02**, an offset datum, while every coordinate in TREK is WGS-84. TREK handles that for
you: a map on an Amap basemap switches to a shifted projection, so markers, routes, clusters and the coordinates you
get from clicking the map all stay where they belong. Nothing is stored differently — only the drawing changes.
Two consequences worth knowing:
- The **satellite toggle** follows the basemap. On an Amap basemap it shows Amap imagery rather than Esri's, because
mixing the two datums on one map would move the photo a few hundred metres out from under the markers.
- Amap has **no coverage outside China**. A trip to Lisbon on an Amap basemap gets a nearly empty map, so this is a
choice for instances whose trips are mostly domestic.
For place *search* via Amap — a separate setting from the basemap — see
[[Places and Search|Places-and-Search]] and [[Environment Variables|Environment-Variables]].
## Mapbox GL — access token and style
Enter your **public token** (`pk.*`) from [mapbox.com → Access tokens](https://console.mapbox.com/account/access-tokens/).
wiki/Places-and-Search.md
+35 -2
View File
@@ -25,7 +25,38 @@ When a key is present, the autocomplete uses the Google Places API, which can re
### Without a Google Maps API key
TREK falls back to OpenStreetMap (Nominatim) automatically — no API key needed. A notice appears above the search box — *Using OpenStreetMap. A Google API key adds ratings and opening hours.* Results include name, address, and coordinates.
TREK falls back to OpenStreetMap (Nominatim) automatically — no API key needed. A notice appears above the search box — *Using OpenStreetMap…* — and what it suggests follows the **Place search provider** setting: a Google key when the provider is Google, an Amap key when it is Amap, either one when the choice is Automatic and neither key is set. When the provider choice is OpenStreetMap the notice stays quiet: that is a decision, not a gap. Results include name, address, and coordinates.
### With an Amap (高德地图) API key
> **Admin:** Set the key in **Admin → Settings → API Keys → 高德地图 API Key**, then pick **Amap** under **Place search
> provider** in the same card. It needs a **Web 服务** (web service) key from
> [console.amap.com](https://console.amap.com/dev/key/app) — a JS API key is a different credential and is rejected.
Google Places is unreachable from most networks inside mainland China, and OpenStreetMap knows very little about
Chinese restaurants, shops and shopping centres. With Amap selected, search, autocomplete, place details and the
reverse geocoding behind right-click-to-add-a-place all go through Amap instead, in Chinese, with ratings, phone
numbers and opening hours where Amap has them.
Amap does not supply place photos here. Its images come with no licence statement TREK could show next to them, so an
Amap place gets its picture from Wikimedia Commons like any other — with the credit and licence attached.
Places remember which provider found them, so switching provider later does not break anything you already saved: an
existing Google place still opens against Google, and vice versa.
You can also paste an Amap share link — `uri.amap.com/marker?…`, `amap.com/place/…`, or a `surl.amap.com` short link —
into the search box, the same way a Google Maps URL works below.
### Which provider answers
**Admin → Settings → API Keys → Place search provider**:
| Setting | What answers place search |
|------------------|-------------------------------------------------------------------------------|
| `Automatic` | Google when a Google key is set, otherwise Amap when an Amap key is, otherwise OpenStreetMap. This is the default and preserves what an existing install already did. |
| `Google Places` | Google. With no Google key, search falls back to OpenStreetMap rather than to Amap. |
| `Amap (高德地图)` | Amap. With no Amap key, search falls back to OpenStreetMap. |
| `OpenStreetMap` | Always OpenStreetMap, ignoring both keys. |
## Place details while searching
@@ -53,10 +84,12 @@ Pictures are copied to your own server and served from there — nothing is load
The column is desktop-only; the mobile place sheet is unchanged.
## Pasting a Google Maps URL
## Pasting a map 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.
Amap links work the same way: `uri.amap.com/marker?…`, `amap.com/place/…` and `surl.amap.com` short links. Their coordinates are converted from GCJ-02 to WGS-84 on the way in, so the place lands where it belongs on every other map.
## Entering coordinates manually
**Paste** a `lat, lng` pair (e.g. `48.8566, 2.3522`) into the **Latitude** field — comma, semicolon or space separated. TREK detects the pair and fills both coordinate fields at once. This works on paste only: the coordinate fields accept digits, a decimal point and a leading minus, so typing a pair by hand drops the separator and leaves a single invalid number (`48.85662.3522`) behind. Type the two values into their own fields instead.