Per-Trip China Map Mode (Amap / GCJ-02)

[davidpopovici01]

Problem

Planning trips in mainland China results in ~500m coordinate offset because Trek uses WGS-84 while Chinese maps use GCJ-02. This makes pins, search results, and routes visually incorrect.

Proposed Solution

Add a use_chinese_map boolean flag to trips. When enabled:

• Map tiles: Amap raster tiles (GCJ-02, no API key needed)
• Search: Amap Web Service API (user-supplied key, server-side only)
• Routing: Amap driving directions (user-supplied key)
• Coordinates: Stored as-is (GCJ-02), no conversion

Public dev key exists for testing purposes, but it has limited daily quota.

Why No Coordinate Conversion

GCJ-02 reverse engineering is legally gray in China. This approach avoids transformations like eviltransform entirely by keeping everything in GCJ-02 for Chinese trips.

Amap APIs Used (Free Tier)

• v3/place/text — search
• v3/place/detail — place details
• v3/direction/driving — routing (150K/month, essentially unlimited)
• v3/assistant/inputtips — excluded (shares 5K/month quota with search, too tight)

Key Storage

Follows existing llm_api_key / UNSPLASH_ACCESS_KEY pattern: encrypted in settings table, env override supported, never sent to browser.

Known Limitations

• WGS-84 imports (GPX/KML) offset inside China trips
• Atlas view shows offset pins for Chinese trips (acceptable)
• POI explore hidden in China mode (Overpass is WGS-84)
• Straight-line fallback if Amap key missing or quota exhausted

Implementation Scope

~35 files, mostly additive. No architectural changes to global map settings.

Questions for Maintainers

1. Is per-trip map mode acceptable.
2. POI explore probably won't work.
3. Is the amap: POI ID prefix acceptable for routing around the placeId.includes(':') → OSM heuristic?

[mauriceboe]

Merging in #1673 (AMap as place search provider). Additional scope from that thread worth folding in: normalize AMap /api/maps/search results into TREK's existing place format (name, address, lat/lng, source, provider POI ID) so planner, Atlas, collections and journey editor need no provider-specific frontend logic; keep existing Google Places / OSM behavior and fallbacks; surface useful errors for invalid keys / quota limits. Open question stays as in this thread: tiles + GCJ-02 (no conversion) vs converting to WGS-84.

[LYJW131]

Running the dev branch on a self-hosted instance in mainland China (Suzhou). Two findings, one about the provider order and one that blocks building dev at all.

1. Amap as a fallback never gets reached in China

places_provider = 'amap' puts Amap behind the index and OpenStreetMap — searchPlaces only asks it once both come back empty. In mainland China they rarely come back empty. They come back irrelevant, which is indistinguishable from a good answer to that check.

Measured on my instance, same query, same bias (Suzhou):

via	first results
index + OpenStreetMap	临顿路（观前街）, 南昌市湾里管理局站前街道办事处 — a government office in Nanchang, 600 km away
Amap	哑巴生煎(临顿路店), 朱华迪苏式生煎·点心, 鑫震源·苏式大虾生煎(临顿路店)

Query was 观前街生煎 (pan-fried dumplings on Guanqian Street). OpenStreetMap returned two rows, so Amap — which has the restaurants — was never asked. 苏州中心商场西西弗书店 does reach Amap and answers correctly, but only because OSM happens to return nothing for it. So the setting an admin picks specifically to fix Chinese search can't fix it.

Suggestion: an explicit choice should answer first; auto keeps today's incumbent-preserving order untouched.

Two things that need to come with it, both found the hard way:

• Gate it on geography. Outside China Amap is not thin, it is wrong, and non-empty wrong: Tokyo Station → KURONO TOKYO (a shop in China), Eiffel Tower → 澳门巴黎人埃菲尔铁塔 (the replica at the Parisian Macao). An "ask Amap, fall through when empty" rule therefore never falls through, and a trip to Paris gets Macao. The caller's own map is the honest signal — every planner search path already sends locationBias — and isOutsideChina() already exists for exactly this, used by reverseGeocode.
• Don't ask twice. With a pinned branch up top and the existing fallback branch below, an empty Amap answer costs two paid calls for one query. The empty answer wants holding and reusing, the way osmAnswer already is.

I have this implemented against dev with tests (AMAP-090..094: a China search answered by Amap alone, a foreign search never reaching it, the empty-answer drop-through with exactly one Amap call, auto unchanged, and autocomplete following the same rule). Happy to open a PR if the direction looks right.

2. dev does not currently build on alpine

docker build fails in the client stage:

Error: Cannot find native binding …
  cause: Error: Cannot find module '@rolldown/binding-linux-x64-musl'
  ❯ [client-builder] RUN npm run build --workspace=client

Vite 8 runs on rolldown, whose platform binding is an optional dependency. npm ci --workspace=client does not install it even though package-lock.json resolves all 15 platforms including linux-x64-musl (npm/cli#4828 — single-workspace installs and optional transitive deps).

Probably unnoticed because the last release (4.2.1, 6 Sep) predates Vite 8 landing on dev, so CI has not built this path yet.

Worked around locally by installing it explicitly after the workspace install, pinned to the rolldown version the lockfile resolves, with --no-save. A stage on glibc would need -gnu instead.

Context that may be useful for the tiles decision

Latencies from a mainland line, direct, no proxy (single 256px tile, warm):

source	result
Amap webrd01.is.autonavi.com	36 ms
OpenStreetMap DE mirror	0.7–1.3 s
OpenFreeMap	2.6–3.2 s
tile.openstreetmap.org, CARTO, Stadia, Google	all time out

GCJ-02 offset, measured against the transform: Suzhou 465 m, Shanghai Bund 479 m, Beijing Forbidden City 556 m — so the gcj02Crs approach in dev is doing real work; the numbers are well past "close enough".

One gotcha worth a line in the docs: isGcj02Basemap() matches on the host (*.is.autonavi.com). A self-hosted tile proxy that pre-corrects the offset and serves it from its own domain is therefore correctly left alone by the CRS — but anyone proxying Amap unchanged under their own hostname will silently lose the correction.

Also, at low zoom Amap answers with 1-bit palette PNGs (z=11 here, 179-byte single-colour tiles). Anything that decodes those tiles server-side needs to handle bit depths below 8; the browser doesn't care, but a proxy does.

[mauriceboe]

Thanks @davidpopovici01 and @LYJW131! Coming in the next big release: with Amap picked as the place search provider, searches and suggestions centred inside China now ask Amap first, and everywhere else the usual order stays, so nothing lands in Macau by accident.