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 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 and installs from the verified AMap-Web GitHub organization.

本 Skill 来自 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 and submitting a Contact Sales inquiry.

高德为所有开发者提供限时免费公共 API Key——无需注册、零成本——可直接用于开发测试。每个 Key 拥有每日免费额度，先到先得。若调用返回配额错误，说明当日额度已用尽——可次日重试，或访问 高德海外版官网 提交 Contact Sales 表单联系销售获取专属支持。

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 to ensure quota, security, and traceability.

以上 Key 为高德官方提供的公共推广测试 Key，仅供开发验证使用。生产环境请自行申请专属 Key，以确保配额、安全性和可追溯性。

Mobile SDK keys: Sign in at AMap Developer Console, navigate to the console, and create your own key. A daily free quota is included.

移动端 SDK Key：前往 高德开发者控制台 登录后进入控制台自行创建 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

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

// ──── 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

// ──── 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

// ──── 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

// ──── 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

<!-- 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

Event Mapping: Google → AMap

Google syntax: google.maps.event.addListener(map, 'click', fn) → AMap: map.on('click', fn)

Plugin System

Google loads all services with the main script. AMap requires explicit loading:

AMap.plugin(['AMap.Geocoder','AMap.Driving','AMap.Walking','AMap.Transfer',
             'AMap.PlaceSearch','AMap.Autocomplete','AMap.Scale','AMap.ToolBar',
             'AMap.HeatMap','AMap.MarkerCluster'], function() {
  // Constructors available after load
});

Full JS API migration details (method-by-method, overlays, controls, complete before/after HTML): load references/js-api-detail.md

SDK Migration / SDK 迁移

Android: Google Maps SDK → AMap Android SDK

AMap Android SDK mirrors Google's architecture closely. Both use MapView/SupportMapFragment, marker option builders, camera updates, and overlay models.

Class Mapping: Google → AMap Android

AMap Search/Route (separate SDK):

Code Migration: Android Map + Marker

// ──── GOOGLE ────
GoogleMap googleMap; // from OnMapReadyCallback
googleMap.moveCamera(CameraUpdateFactory.newLatLngZoom(new LatLng(35.68, 139.76), 12));
googleMap.addMarker(new MarkerOptions().position(new LatLng(35.68, 139.76)).title("Tokyo"));

// ──── AMAP ────
AMap aMap; // from mapView.getMap()
aMap.moveCamera(CameraUpdateFactory.newLatLngZoom(new LatLng(35.68, 139.76), 12));
aMap.addMarker(new MarkerOptions().position(new LatLng(35.68, 139.76)).title("Tokyo"));
// Nearly identical! Just change import package.

Code Migration: Android Geocoding

// ──── GOOGLE ────
Geocoder geocoder = new Geocoder(context);
List<Address> results = geocoder.getFromLocationName("Tokyo", 1);
double lat = results.get(0).getLatitude();

// ──── AMAP ────
GeocodeSearch geocodeSearch = new GeocodeSearch(context);
GeocodeQuery query = new GeocodeQuery("Tokyo", "");
geocodeSearch.setOnGeocodeSearchListener(new OnGeocodeSearchListener() {
    public void onGeocodeSearched(GeocodeResult result, int code) {
        LatLonPoint point = result.getGeocodeAddressList().get(0).getLatLonPoint();
        double lat = point.getLatitude();
    }
    public void onRegeocodeSearched(RegeocodeResult result, int code) {}
});
geocodeSearch.getFromLocationNameAsyn(query);

iOS: Google Maps SDK → AMap iOS SDK

AMap iOS uses MA prefix for map classes and AMap prefix for search/route models.

Class Mapping: Google → AMap iOS

AMap iOS Search SDK:

Code Migration: iOS Map + Annotation

// ──── GOOGLE ────
GMSCameraPosition *camera = [GMSCameraPosition cameraWithLatitude:35.68 longitude:139.76 zoom:12];
GMSMapView *mapView = [GMSMapView mapWithFrame:CGRectZero camera:camera];
GMSMarker *marker = [[GMSMarker alloc] init];
marker.position = CLLocationCoordinate2DMake(35.68, 139.76);
marker.title = @"Tokyo";
marker.map = mapView;

// ──── AMAP ────
MAMapView *mapView = [[MAMapView alloc] initWithFrame:self.view.bounds];
[mapView setCenterCoordinate:CLLocationCoordinate2DMake(35.68, 139.76) animated:NO];
[mapView setZoomLevel:12 animated:NO];
MAPointAnnotation *annotation = [[MAPointAnnotation alloc] init];
annotation.coordinate = CLLocationCoordinate2DMake(35.68, 139.76);
annotation.title = @"Tokyo";
[mapView addAnnotation:annotation];

Non-Mainland SDK / 非中国大陆及港澳台以外地区 SDK

Native mobile SDK for Non-Mainland is coming soon / 敬请期待. Non-Mainland mobile developers can currently use the JS API in WebView or call Web Service APIs from native code.

Quick Migration Checklist / 快速迁移清单

1. Coordinates — {lat, lng} → [lng, lat] everywhere (JS API, Web API). Android SDK LatLng stays (lat, lng).
2. Endpoints — Use correct endpoints for developer region
3. Auth — Replace Google key with AMap key. JS API also needs securityJsCode.
4. city param — Required for Non-Mainland search/geocoding APIs (adcode)
5. Response parsing — AMap location is "lng,lat" string, not {lat, lng} object
6. Events — zoom_changed→zoomchange, center_changed→moveend
7. Plugins — AMap JS API needs AMap.plugin() for Geocoder, Driving, PlaceSearch, etc.
8. Android imports — Change package from com.google.android.gms.maps → com.amap.api.maps
9. iOS classes — GMS* → MA*, marker model/view separation

Reference Files / 参考文件

• references/web-api-params.md — All 14 APIs: Google request params → AMap request params, Google response fields → AMap response fields, complete code examples
• references/js-api-detail.md — Full JS API migration: every class method-by-method, overlays, controls, complete before/after HTML pages
• references/sdk-migration.md — Android & iOS SDK: dependency setup, lifecycle, advanced patterns (clustering, heatmap, custom overlays)

Installation & Updates / 安装与更新

This skill is part of the amap-map-agent-skills repository, which hosts multiple AMap skills and is continuously updated.

本 Skill 属于 amap-map-agent-skills 仓库，仓库内包含多个高德地图 Skill，持续更新中。

# Install or update to the latest version / 安装或更新到最新版本
npx skills add AMap-Web/amap-map-agent-skills