Guide to Integrating AMap HarmonyOS Map SDK

This document introduces the AMap (Gaode) Map SDK that has been fully adapted for HarmonyOS and is released for free to developers. It provides an overview of the SDK’s features, the migration path from Android, and step‑by‑step instructions for integrating the SDK into HarmonyOS applications.

Key Features

Seamless switch from the Android Map SDK to the HarmonyOS Map SDK without additional development effort.

Underlying engine connects to HarmonyOS NDK, and all system interfaces use HarmonyOS APIs.

Supports map rendering, search, route planning, coordinate conversion, distance measurement, area calculation, and extensive customization of map elements.

The SDK also retains compatibility with custom SaaS platforms, allowing developers to style maps with over 40 map elements across seven categories.

Integration Steps (From Scratch)

1. Set up the HarmonyOS development environment

Install DevEco Studio, configure the environment, and create a new project following the official HarmonyOS documentation.

2. Configure the application’s signature information

After creating the project, configure the signing information to enable real‑device debugging and app publishing.

3. Obtain the appId

Retrieve the appId, which is required to request an AMap API Key. The appId format is packageName_signature . Example:

com.amap.demo_BGtGgVB3ASqU7XXXXV2/zhoYh6tFQHAd5DASWVTEAgvZfzrEGljjs=

4. Apply for an API Key on the AMap Open Platform

Create a new application in the console, add a new Key bound to the “Harmony Platform SDK” service, and submit the request.

5. Set the API Key in code

/**
 * Dynamically set the API Key.
 * @param apiKey The API Key obtained from the AMap website.
 */
MapsInitializer.setApiKey(String apiKey);

Make sure to set the key before invoking any AMap SDK interfaces, preferably in the Application’s initialization.

Using the SDK – Creating a Map

Configure config.json with required permissions, e.g.:

...
"reqPermissions": [
  {
    "usedScene": {
      "ability": ["com.example.harmonysearchsdk.MainAbility"],
      "when": "always"
    },
    "reason": "request internet",
    "name": "ohos.permission.INTERNET"
  }
]
...

Add the .har package to the libs directory and declare the dependency:

dependencies {
    implementation files("libs/xxx.har")
    // ...
}

Or include all .har files:

dependencies {
    implementation fileTree(dir: 'libs', include: ['*.jar', '*.har'])
    // ...
}

Initialize the map view in an Ability:

public class BasicMapDemoSlice extends Ability {
    private MapView mapView;
    @Override
    protected void onStart(Intent intent) {
        super.onStart(intent);
        initMapView();
    }
    private void initMapView() {
        mapView = new MapView(this);
        mapView.onCreate(null);
        mapView.onResume();
        DirectionalLayout.LayoutConfig config = new DirectionalLayout.LayoutConfig(
                DirectionalLayout.LayoutConfig.MATCH_PARENT, DirectionalLayout.LayoutConfig.MATCH_PARENT);
        mapView.setLayoutConfig(config);
        super.setUIContent(mapView);
    }
    @Override
    protected void onStop() {
        super.onStop();
        if (mapView != null) {
            mapView.onDestroy();
        }
    }
}

Obtain the AMap object and set listeners:

AMap aMap = mapView.getMap();
aMap.setOnMapLoadedListener(new AMap.OnMapLoadedListener() {
    @Override
    public void onMapLoaded() {
        // todo
    }
});

After these steps, the map will be displayed and developers can add markers, polylines, polygons, and other overlays.

Further Resources

Visit the AMap Open Platform for SDK downloads, documentation, demos, and support: https://lbs.amap.com/

HarmonyOS SDK details: https://lbs.amap.com/api/harmonyos-sdk/summary/

Join the HarmonyOS SDK developer community via DingTalk QR code for technical exchanges.