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

This Skill comes from the amap-map-agent-skills repository (current version:1.0.0). The Skill in the repository is continuously updated, covering new APIs, bug fixes, and improvements. Developers are advised to regularly run the above command to get the latest version.

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.

AMap and Google Maps use the sameimperative, object-orienteddesign. Migration does not require architectural changes—the main work is switching interfaces and SDKs to the corresponding AMap equivalents, and adapting the related methods and calling conventions.

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.

AMap provides all developers with alimited-time free public API Key—no registration required, zero cost—and it can be used directly for development and testing. Each Key has a daily free quota, available on a first-come, first-served basis. If a call returns a quota error, it means the daily quota has been used up—you can retry the next day, or visit AMap International Website to submit the Contact Sales form and contact sales for dedicated support.

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

The above Key is apublic promotional test Keyprovided by AMap, and is for development verification only.For production environments, apply for your own dedicated Keyto ensure quota, security, and traceability.

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

Mobile SDK Key: go to AMap Developer Console and log in, then enter the console to create a Key yourself. It also provides a certain free daily quota. The Web/JS public Key is not applicable to the mobile SDK.

Pricing Advantage / 价格优势

Same capabilities, half the price — AMap's pricing tiers align with Google Maps but cost roughly 50% less.

Same capabilities, half the price—AMap's pricing tiers align with Google Maps, at about 50% lower cost.

---

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.

  ⚠️ The non-mainland positioning API currently uses the HTTP protocol and accepts device identifiers such as MAC/IMEI. In production environments, it is recommended to use HTTPS first to avoid transmitting sensitive data in plaintext.

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

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)
new google.maps.Polyline({path, ...})	new AMap.Polyline({path, ...})	path arrays: {lat,lng} → [lng,lat]
new google.maps.Polygon({paths, ...})	new AMap.Polygon({path, ...})	paths → path (singular)
new google.maps.Circle({center, radius})	new AMap.Circle({center, radius})	center reversed
new google.maps.LatLng(lat, lng)	new AMap.LngLat(lng, lat)	Both name and param order differ
new google.maps.Geocoder()	AMap.plugin('AMap.Geocoder', cb)	Must load plugin first
new google.maps.DirectionsService()	AMap.plugin('AMap.Driving', cb)	Separate plugins per mode
new google.maps.places.PlacesService(map)	AMap.plugin('AMap.PlaceSearch', cb)	Plugin
new google.maps.places.Autocomplete(input)	AMap.plugin('AMap.Autocomplete', cb)	Plugin
marker.setMap(null)	marker.setMap(null) or map.remove(marker)	Same or cleaner
map.setCenter({lat, lng})	map.setCenter([lng, lat])	Coord order
map.fitBounds(bounds)	map.setBounds(bounds)	Method name differs

Event Mapping: Google → AMap

Google Event	AMap Event	Google Access	AMap Access
'click'	'click'	e.latLng.lat()	e.lnglat.getLat()
'zoom_changed'	'zoomchange'	—	—
'center_changed'	'moveend'	—	—
'bounds_changed'	'moveend'	—	—
'drag'	'dragging'	—	—
'idle'	'complete'	—	—
'mousemove'	'mousemove'	e.latLng	e.lnglat

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

Google Maps Android SDK	AMap Android SDK	Notes
com.google.android.gms.maps.GoogleMap	com.amap.api.maps.AMap	Core map controller
com.google.android.gms.maps.MapView	com.amap.api.maps.MapView	Map widget
com.google.android.gms.maps.SupportMapFragment	com.amap.api.maps.SupportMapFragment	Fragment
com.google.android.gms.maps.model.LatLng	com.amap.api.maps.model.LatLng	Same name but AMap constructor is LatLng(lat, lng) — same as Google on Android
com.google.android.gms.maps.model.Marker	com.amap.api.maps.model.Marker	Same pattern
com.google.android.gms.maps.model.MarkerOptions	com.amap.api.maps.model.MarkerOptions	Same builder pattern
com.google.android.gms.maps.model.Polyline	com.amap.api.maps.model.Polyline	Same
com.google.android.gms.maps.model.PolylineOptions	com.amap.api.maps.model.PolylineOptions	Same
com.google.android.gms.maps.model.Polygon	com.amap.api.maps.model.Polygon	Same
com.google.android.gms.maps.model.Circle	com.amap.api.maps.model.Circle	Same
com.google.android.gms.maps.model.CircleOptions	com.amap.api.maps.model.CircleOptions	Same
com.google.android.gms.maps.model.CameraPosition	com.amap.api.maps.model.CameraPosition	Same builder
com.google.android.gms.maps.CameraUpdateFactory	com.amap.api.maps.CameraUpdateFactory	Same factory
com.google.android.gms.maps.model.BitmapDescriptorFactory	com.amap.api.maps.model.BitmapDescriptorFactory	Same
GoogleMap.OnMapClickListener	AMap.OnMapClickListener	Same interface pattern
GoogleMap.OnMarkerClickListener	AMap.OnMarkerClickListener	Same
com.google.android.gms.maps.model.GroundOverlay	com.amap.api.maps.model.GroundOverlay	Same

AMap Search/Route (separate SDK):

Google Play Services	AMap Services SDK	Notes
com.google.android.libraries.places.api.model.Place	com.amap.api.services.core.PoiItem	POI result
com.google.maps.GeocodingApi	com.amap.api.services.geocoder.GeocodeSearch	Geocoding
com.google.maps.DirectionsApi	com.amap.api.services.route.RouteSearch	Route planning
com.google.maps.DistanceMatrixApi	com.amap.api.services.route.DistanceSearch	Distance

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

Google Maps iOS SDK	AMap iOS SDK	Notes
GMSMapView	MAMapView	Core map view
GMSMarker	MAPointAnnotation + MAAnnotationView	AMap separates data model from view
GMSPolyline	MAPolyline + MAPolylineRenderer	AMap separates overlay from renderer
GMSPolygon	MAPolygon + MAPolygonRenderer	Same pattern
GMSCircle	MACircle + MACircleRenderer	Same pattern
GMSCameraPosition	MAMapStatus	Camera state
GMSCoordinateBounds	MACoordinateRegion	Bounds
CLLocationCoordinate2D	CLLocationCoordinate2D	Same (both use CoreLocation)
GMSGeocoder	AMapSearchAPI + AMapGeocodeSearchRequest	Search SDK
GMSPath	MAPolyline coordinates	Different approach
GMSMapViewDelegate	MAMapViewDelegate	Same delegate pattern

AMap iOS Search SDK:

Google	AMap iOS Search SDK	Notes
Places SDK GMSPlacesClient	AMapSearchAPI + AMapPOIKeywordsSearchRequest	POI search
Directions	AMapSearchAPI + AMapDrivingRouteSearchRequest	Route
Geocoding	AMapSearchAPI + AMapGeocodeSearchRequest	Geocode

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.

This Skill belongs to amap-map-agent-skills repository. The repository contains multiple AMap Skills and is continuously updated.

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