amap-map-google-maps-migration（amap MAP Google maps 迁移）

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).

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 swapping API and SDK calls with corresponding AMap equivalents, and adapting the related methods and calling conventions.

高德与 Google Maps 采用相同的命令式、面向对象设计。迁移不需要架构变更——主要工作是将 API 和 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 complimentary public API keys so developers can start testing immediately. 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 表单联系销售获取专属支持。

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，同样每日提供一定免费额度。

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.

Pricing Advantage / 价格优势

AMap pricing tiers align with Google Maps, but at roughly half the cost for the same capabilities. Same capabilities, half the price.

高德定价层级与 Google Maps 完全对齐，同等能力价格约为 Google 的一半。

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.
• Geolocation HTTP: The Non-Mainland Geolocation endpoint (sg-apilocate.opnavi.com) uses HTTP, not HTTPS, and accepts sensitive device identifiers (MAC, IMEI). Use HTTPS in production where supported.
• Multi-language: AMap langCode supports zh/en/ja/ko and 18 more languages.

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

Native mobile SDK for Non-Mainland (excl. HK/MO/TW) regions 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. Domain — Use correct domain 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)

Version & Updates / 版本与更新

Current version: 1.0.1. To install or update to the latest version:

npx skills add AMap-Web/amap-map-agent-skills

npx skills add is the official installation method provided by skills.sh and installs from the verified AMap-Web GitHub organization.