[FEATURE] Add AMap (Gaode) as a place search provider for mainland China

[luckjiawei]

What to build

Place search in mainland China is currently limited by the available providers. TREK uses Google Places when a Google Maps API key is configured and falls back to OpenStreetMap/Nominatim without one. Google services may be unavailable or incomplete in mainland China, while OpenStreetMap can have limited Chinese POI coverage and less accurate local place-name matching.

Add AMap (Gaode Maps) as an optional place search provider. AMap has substantially better POI coverage, Chinese place names, and structured addresses for mainland China.

An administrator should be able to configure a separate AMap Web Service API key and select which provider TREK uses for place search. Existing Google Places and OpenStreetMap behavior should remain available.

The first implementation can focus on /api/maps/search. AMap results should be normalized to the existing TREK place result format so the current planner, Atlas, collections, journey editor, and other search consumers continue to work without provider-specific handling.

AMap returns coordinates in GCJ-02, while TREK's existing OpenStreetMap, Mapbox, GPX, and KML data generally use WGS-84. AMap coordinates therefore need to be converted to WGS-84 before they are stored or displayed, otherwise markers in mainland China may be offset by several hundred meters.

Autocomplete, place details, reverse geocoding, and other AMap capabilities can be added later, with the existing providers used as fallbacks where AMap does not yet have an implementation.

AMap Place Search API documentation:

https://lbs.amap.com/api/webservice/guide/api/newpoisearch

Acceptance criteria

• An administrator can configure a separate AMap Web Service API key
• AMap can be selected as the place search provider without replacing or overwriting the existing Google Maps API key
• /api/maps/search can search places using the AMap Place Search API
• AMap results are returned using TREK's existing place search result structure, including name, address, latitude, longitude, and source
• AMap results include their provider-specific POI ID so future details and deduplication support can be added
• GCJ-02 coordinates returned by AMap are converted to WGS-84 before being stored or displayed on TREK's existing maps
• Chinese POI names and structured addresses are preserved correctly
• Invalid API keys, quota limits, and upstream AMap errors produce useful error messages
• Existing Google Places and OpenStreetMap search behavior remains unchanged
• Search consumers such as the trip planner, Atlas, collections, and journey editor can use AMap results without provider-specific frontend logic
• Automated tests cover result normalization, API errors, provider selection, and coordinate conversion

Blocked by

None - can start immediately.

Related issues

None found.

[davidpopovici01]

I believe we need to use amap tiles in order to have places exist in Chinese space rather than convert them to WGS-84, which is a legal grey area.

This tile map is free, and does not need an API key

[mauriceboe]

Closed as duplicate of #1636, which covers AMap for mainland China. Note the two threads differ on approach: #1636 keeps coordinates in GCJ-02 with AMap tiles (no conversion), while this one proposed GCJ-02 -> WGS-84 conversion. Consensus in both threads leans toward the tile-based, no-conversion approach since GCJ-02 conversion is a legal grey area. Continuing in #1636.