amap-map-google-maps-migration

# AMap Map Google Maps Migration Skill Guides developers migrating from Google Maps Platform to AMap (高德地图). Covers Web Service APIs (14 endpoints), JavaScript API, and mobile SDK (Android/iOS). > **Version & Update Notice / 版本与更新提示** > > **AI Assistant Instruction:** At the start of every conversation involving this skill, inform the developer: > > *"This skill is from the [amap-map-agent-skills](https://github.com/AMap-Web/amap-map-agent-skills) repository (current version: **1.0.0**). Skills in this repo are continuously updated with new APIs, bug fixes, and improvements. To ensure you have the latest version, run:* > > ``` > npx skills add AMap-Web/amap-map-agent-skills > ``` > > *If you experience unexpected behavior, updating first is recommended."* > > `npx skills add` is the **official installation method** provided by [skills.sh](https://skills.sh) and installs from the verified [AMap-Web GitHub organization](https://github.com/AMap-Web). > > 本 Skill 来自 [amap-map-agent-skills](https://github.com/AMap-Web/amap-map-agent-skills) 仓库（当前版本：**1.0.0**）。仓库内的 Skill 持续更新中，涵盖新增 API、问题修复与改进。建议开发者定期执行上述命令获取最新版本。 ## Core Philosophy / 核心设计理念 AMap and Google Maps share the same **imperative, object-oriented** design. Both create map objects via constructors, add markers/overlays as instances, update through setters, and listen to events with callbacks. Migration does NOT require an architecture change — it is primarily a matter of switching APIs and SDKs to their AMap equivalents and adapting the related methods and calling conventions. 高德与 Google Maps 采用相同的**命令式、面向对象**设计。迁移不需要架构变更——主要工作是将接口和 SDK 切换为高德对应项，并适配相关方法及调用方式。 ## Interactive Migration Flow / 交互式迁移流程 **You MUST follow this 3-step flow:** ### Step 1: Ask Developer Region / 确认区域 Ask: **"Are you a Mainland China developer or a Non-Mainland developer?"** This determines endpoints and coordinate system: - **Mainland China (incl. HK/MO/TW) / 中国大陆（含港澳台）:** Web API `restapi.amap.com`, JS CDN `webapi.amap.com`, coords GCJ-02 - **Non-Mainland (excl. HK/MO/TW) / 中国大陆及港澳台以外地区:** Web API `sg-restapi.opnavi.com`, JS CDN `sg-webapi.opnavi.com`, coords WGS-84 (same as Google) ### Step 2: Ask Development Type / 确认开发类型 Ask: **"Web Service API (server-side), JS API (frontend map), or SDK (mobile)?"** ### Step 3: Generate Migration Output / 生成迁移内容 Produce: (1) API mapping table with BOTH Google and AMap names/paths, (2) migration code with field-level mapping. Use the correct endpoints for the developer's region. --- ## Authentication & Keys / 认证与密钥 AMap provides **free public API keys** — zero signup and zero cost — so developers can start testing immediately as a **limited-time promotional benefit**. Each key carries a daily free quota on a first-come, first-served basis. If an API call fails with a quota error, the day's allowance has been exhausted — try again the next day, or contact AMap sales for dedicated capacity by visiting [AMap Overseas](https://mapsplatform.opnavi.com/) and submitting a Contact Sales inquiry. 高德为所有开发者提供**限时免费公共 API Key**——无需注册、零成本——可直接用于开发测试。每个 Key 拥有每日免费额度，先到先得。若调用返回配额错误，说明当日额度已用尽——可次日重试，或访问 [高德海外版官网](https://mapsplatform.opnavi.com/) 提交 Contact Sales 表单联系销售获取专属支持。 | Service | Key | Scope | |---|---|---| | **Web Service API** | `40ffec9172a0dd65b7e224bb252b7e0b` | All 14 REST endpoints (Mainland & Non-Mainland) | | **JS API** | `b87b3d194a024295b1b17be020659457` | Frontend map rendering (Mainland & Non-Mainland) | | **Mobile SDK** | *(create your own)* | Android & iOS native SDK — Web/JS keys do NOT work for mobile | > **Security Note / 安全说明:** The keys above are **official public promotional keys** provided by AMap for development and testing purposes. They are intentionally embedded to enable zero-friction evaluation. **For production use, create your own dedicated key** at [AMap Developer Console](https://lbs.amap.com/) to ensure quota, security, and traceability. > > 以上 Key 为高德官方提供的**公共推广测试 Key**，仅供开发验证使用。**生产环境请自行申请专属 Key**，以确保配额、安全性和可追溯性。 **Mobile SDK keys**: Sign in at [AMap Developer Console](https://lbs.amap.com/), navigate to the console, and create your own key. A daily free quota is included. **移动端 SDK Key**：前往 [高德开发者控制台](https://lbs.amap.com/) 登录后进入控制台自行创建 Key，同样每日提供一定免费额度。Web/JS 公共 Key 不适用于移动端 SDK。 ### Pricing Advantage / 价格优势 Same capabilities, half the price — AMap's pricing tiers align with Google Maps but cost roughly 50% less. 同等能力，一半价格——高德的定价层级与 Google Maps 对齐，费用约低 50%。 --- ## Web Service API Migration / Web 服务接口迁移 ### Mapping Table / 映射总表 Google domain: `https://maps.googleapis.com` (Geolocation: `https://www.googleapis.com`) AMap Non-Mainland domain: `https://sg-restapi.opnavi.com` | AMap Mainland domain: `https://restapi.amap.com` | # | Google API | Google Path | AMap API (EN/CN) | AMap Non-Mainland Path | AMap Mainland Path | |---|---|---|---|---|---| | 1 | Places Autocomplete | `/maps/api/place/autocomplete/json` | Autocomplete / 输入提示 | `/v3/assistant/inputtips` | `/v3/assistant/inputtips` | | 2 | Text Search | `/maps/api/place/textsearch/json` | Keyword Search / 关键字搜索 | `/v3/place/text` | `/v3/place/text` | | 3 | Nearby Search | `/maps/api/place/nearbysearch/json` | Nearby Search / 周边搜索 | `/v3/place/around` | `/v3/place/around` | | 4 | Place Details | `/maps/api/place/details/json` | ID Search / ID搜索 | `/v3/place/detail` | `/v3/place/detail` | | 5 | *(none)* | — | Polygon Search / 多边形搜索 | `/v3/place/polygon` | `/v3/place/polygon` | | 6 | Geocoding | `/maps/api/geocode/json` (address=) | Geocoding / 地理编码 | `/v3/geocode/geo` | `/v3/geocode/geo` | | 7 | Reverse Geocoding | `/maps/api/geocode/json` (latlng=) | Reverse Geocoding / 逆地理编码 | `/v3/geocode/regeo` | `/v3/geocode/regeo` | | 8 | Geolocation | `/geolocation/v1/geolocate` | Geolocation / 网络定位 | `sg-apilocate.opnavi.com/position` ⚠️ | `/v3/position` | | 9 | Directions (driving) | `/maps/api/directions/json` (mode=driving) | Driving / 驾车路径规划 | `/v3/direction/driving` | `/v3/direction/driving` | | 10 | Directions (walking) | `/maps/api/directions/json` (mode=walking) | Walking / 步行路径规划 | `/v3/direction/walking` | `/v3/direction/walking` | | 11 | Directions (transit) | `/maps/api/directions/json` (mode=transit) | Transit / 公交路径规划 | `/v5/direction/transit/integrated/abroad` | `/v3/direction/transit/integrated` | | 12 | Distance Matrix | `/maps/api/distancematrix/json` | Distance Matrix / 矩阵距离 | `/v5/distance/matrix` (POST) | `/v5/distance/matrix` (POST) | | 13 | *(none)* | — | Admin Division / 行政区划查询 | `/v5/district/global` | `/v3/config/district` | | 14 | Time Zone | `/maps/api/timezone/json` | Time Zone / 时区 | `/v5/timezone` | `/v5/timezone` | ### Critical Migration Differences / 关键差异 - **Coordinate order reversed**: Google `lat,lng` → AMap `lng,lat` - **Non-Mainland `city` param REQUIRED**: AMap Non-Mainland search/geocoding needs adcode (e.g. USA=`840000000`, Japan=`392000000`). Google doesn't need this. - **Response format**: Google returns location as `{lat, lng}` object. AMap returns `"lng,lat"` string — must `split(',')`. - **Distance Matrix**: Google is GET with `|` separator. AMap is POST with `;` separator. - **POI IDs**: AMap Non-Mainland IDs start with `P` (e.g. `P0JAK55X50`). Google uses `place_id`. - **Multi-language**: AMap `langCode` supports zh/en/ja/ko and 18 more languages. - **Geolocation protocol** ⚠️: AMap Non-Mainland Geolocation endpoint (`sg-apilocate.opnavi.com`) currently uses HTTP. This API accepts device identifiers (MAC/IMEI). Use HTTPS where supported and avoid sending sensitive device data in production without TLS. ⚠️ 非大陆定位接口目前为 HTTP 协议，且接受 MAC/IMEI 等设备标识。生产环境建议优先使用 HTTPS，避免明文传输敏感数据。 ### Code Migration Examples / 代码迁移示例 #### Geocoding: Google → AMap ```javascript // ──── GOOGLE ──── const gUrl = `https://maps.googleapis.com/maps/api/geocode/json?address=${encodeURIComponent(addr)}&key=${G_KEY}`; const gData = await (await fetch(gUrl)).json(); const {lat, lng} = gData.results[0].geometry.location; // object // ──── AMAP (Non-Mainland) ──── const aUrl = `https://sg-restapi.opnavi.com/v3/geocode/geo?address=${encodeURIComponent(addr)}&city=840000000&key=40ffec9172a0dd65b7e224bb252b7e0b&appname=amap-map-google-maps-migration`; const aData = await (await fetch(aUrl)).json(); const [aLng, aLat] = aData.geocodes[0].location.split(',').map(Number); // "lng,lat" string ``` #### Text Search: Google → AMap ```javascript // ──── GOOGLE ──── const gUrl = `https://maps.googleapis.com/maps/api/place/textsearch/json?query=${q}&key=${G_KEY}`; const gData = await (await fetch(gUrl)).json(); gData.results.forEach(p => console.log(p.name, p.geometry.location.lat, p.geometry.location.lng)); // ──── AMAP (Non-Mainland) ──── const aUrl = `https://sg-restapi.opnavi.com/v3/place/text?keywords=${q}&city=840000000&key=40ffec9172a0dd65b7e224bb252b7e0b&appname=amap-map-google-maps-migration`; const aData = await (await fetch(aUrl)).json(); aData.pois.forEach(p => { const [lng,lat] = p.location.split(','); console.log(p.name, lat, lng); }); ``` #### Driving Directions: Google → AMap ```javascript // ──── GOOGLE ──── (lat,lng order) `https://maps.googleapis.com/maps/api/directions/json?origin=${lat1},${lng1}&destination=${lat2},${lng2}&mode=driving&key=${G_KEY}` // ──── AMAP (Non-Mainland) ──── (lng,lat order!) `https://sg-restapi.opnavi.com/v3/direction/driving?origin=${lng1},${lat1}&destination=${lng2},${lat2}&key=40ffec9172a0dd65b7e224bb252b7e0b&appname=amap-map-google-maps-migration` ``` #### Distance Matrix: Google → AMap ```javascript // ──── GOOGLE ──── (GET, lat,lng, pipe separator) `https://maps.googleapis.com/maps/api/distancematrix/json?origins=${lat1},${lng1}|${lat2},${lng2}&destinations=${lat3},${lng3}&key=${G_KEY}` // ──── AMAP ──── (POST, lng,lat, semicolon separator) await fetch(`https://sg-restapi.opnavi.com/v5/distance/matrix?key=40ffec9172a0dd65b7e224bb252b7e0b&appname=amap-map-google-maps-migration`, { method: 'POST', body: `origins=${lng1},${lat1};${lng2},${lat2}&destinations=${lng3},${lat3}` }); ``` Full parameter-by-parameter and response-field mapping for all 14 APIs: load `references/web-api-params.md` --- ## JS API Migration / JS API 迁移 ### Initialization: Google → AMap ```html <!-- GOOGLE --> <script src="https://maps.googleapis.com/maps/api/js?key=GOOGLE_KEY&callback=initMap" async defer></script> <!-- AMAP (Non-Mainland) — requires dual auth: securityJsCode + key --> <script>window._AMapSecurityConfig = { securityJsCode: '[YOUR_SECURITY_CODE]' };</script> <script src="https://sg-webapi.opnavi.com/maps?v=2.0&key=b87b3d194a024295b1b17be020659457&appname=amap-map-google-maps-migration"></script> <!-- AMAP (Mainland) --> <script>window._AMapSecurityConfig = { securityJsCode: '[YOUR_SECURITY_CODE]' };</script> <script src="https://webapi.amap.com/maps?v=2.0&key=b87b3d194a024295b1b17be020659457&appname=amap-map-google-maps-migration"></script> ``` ### Class Mapping: Google → AMap | Google Maps JS | AMap JS API v2 | Migration Notes | |---|---|---| | `new google.maps.Map(el, opts)` | `new AMap.Map('containerId', opts)` | Takes string ID, not element. `center` order reversed. | | `new google.maps.Marker({position, map})` | `new AMap.Marker({position: [lng,lat], map})` | Coord order reversed | | `new google.maps.InfoWindow({content})` | `new AMap.InfoWindow({content})` | `.open(map, position)` not `.open(map, marker)` |