HERE Android SDK Developer's Guide

Create a Simple App Using the HERE SDK

This tutorial provides instructions on how to create a simple application that uses the HERE Android SDK to render a map on an Android device.

This tutorial assumes that you are using the Android Studio development environment. Development tasks for this basic application include:
  • Acquire HERE credentials for accessing map services.
  • Create a new Android Studio project.
  • Add necessary resources, permissions, and a map fragment to the project.
  • Modify AndroidManifest.xml
  • Initialize the map fragment to create a map instance and associate this map with the map fragment for rendering on the client device.

Acquire HERE SDK Credentials

Typically, before developing a new HERE SDK application, you need to acquire a set of credentials by registering your application on Each application requires a unique set of credentials. When you register your app, the registered bundle identifier must match the package name in your project.

Create a New Android Studio Project

The second stage of developing an application using the HERE SDK is to create a new project in Android Studio as follows:

  1. From the Welcome to Android Studio dialogue box, select Start a new Android Studio project to open the Create New Project dialog.
  2. In the New Android Application dialog, under Application name, specify an appropriate application name. The remainder of this tutorial uses BasicMapSolution as the application name.
  3. Under Company Domain, specify an appropriate domain.
  4. Edit the package name by clicking the Edit link. The remainder of this tutorial uses as the package name.
    Figure 1. Edit the Package Name
  5. Under Project Location, specify an appropriate project location in the file system.
  6. Click Next.
  7. Select the form factors supported by your application. For the purpose of this tutorial, check Phone and Tablet.
  8. Under Minimum SDK, select the lowest version of the Android SDK you wish to support. For this sample application, use Android 4.1.x "Jelly Bean".
  9. Click Next.
  10. You may be prompted to agree to a License Agreement. Click Accept, and then Next to install SDK components. After the installation is complete, click Next again.
  11. In the "Add an activity to Mobile" dialog box, select Empty Activity and click Next.
  12. In the "Configure Activity" dialog box, specify an appropriate activity name in Activity Name. This tutorial uses the name BasicMapActivity.
  13. Under Layout Name, specify an appropriate layout name. (This tutorial uses activity_main.)
  14. Click Finish.

Result: Andriod Studio creates the structure for your project and opens the development environment.

A few views are available in the Android Studio development environment. The Android view shows a flattened view of the application's structure, and the Project view shows a flattened view of the project's structure, including Gradle-related files.

The Android view provides quick access to key source files of your Android application. Selecting the activity_main.xml file in Android view opens the file in the Layout Editor and allows you to drag-and-drop widgets into your layout.

The following image shows how to switch between Android and Project view.

Figure 2. Switching Views in Android Studio

Import the HERE SDK Android Archive

The HERE Android SDK library is shipped as an Android Archive (.AAR) file. You can import this library by doing the following:

  1. On the View menu, click Tool Windows > Project.
  2. A few tabs are available in this tool window. Select the Project tab to show a file system view of the application structure.
  3. In your operating system's file system, navigate to the extracted HERE SDK directory. Copy the HERE-sdk.aar file and paste it into the libs directory.
  4. Optional: To enable quick Javadoc reference within your Android Studio environment, scroll down to the External Libraries section, right-click on HERE-sdk, and then select Library Properties. Click the + button and locate HERE-sdk-javadoc.jar from the HERE SDK package.

Modify build.gradle

After importing the .AAR file, modify build.gradle to add the file to your list of dependencies.

  1. From the Project view pane, locate the build.gradle file under the app folder and open it for editing.
  2. In build.gradle, add the following line into the android { ... } section:
    repositories {
      flatDir {
        dirs 'libs'
  3. Next, add the following into the dependencies { ... } section:
    implementation(name:'HERE-sdk', ext:'aar')
  4. Optional: Add the JTS Topology Suite (version 1.15.0 or later) library, which is used for rendering complex polygons.
    You can add this library by adding the following line into the dependencies { ... } section of the build.gradle file:
    implementation 'org.locationtech.jts:jts-core:1.15.0'
  5. Optional: If you plan on extending this application with HERE Places or Routing functionality, add the GSON library to your project. You can add this library by adding the following line into the dependencies { ... } section:
    implementation ''

Modify AndroidManifest.xml and Add HERE Credentials

  1. Add the HERE credentials to AndroidManifest.xml. For instructions on how to edit this file, see Authenticating Applications.
  2. Modify the opening <application> by adding the android:hardwareAccelerated="true" attribute.
    <application android:icon="@drawable/icon"
    android:label="@string/app_name" android:hardwareAccelerated="true">
  3. Add the following markup before the <application></application> tags:
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
    Note: If your app uses Android API level 23 (Android 6.0) or above, you must also add code to request for permissions during runtime. You can find more information in the Request for Permissions section.
  4. Optional: To enable quick javadoc reference within your Android Studio environment, click on .idea/libraries/HERE_sdk.xml to edit it, and then add the following after </CLASSES> and before <SOURCES />:
      <root url="jar://$PROJECT_DIR$/app/libs/HERE-sdk-javadoc.jar!/" />

Result: Your project is able to make use of APIs from the HERE SDK.

Edit activity_main.xml

Along with permissions and credentials, you must add an Android <fragment /> tag to set up the map fragment that your application activity is associated with. In this section, we add a text label (generated as part of the default new application) and a map as follows:

  1. From the Android View, under the res/layout/ folder of your project, double-click the activity_main.xml file to open it for editing.
  2. Ensure that the XML file has <LinearLayout></LinearLayout> as its root element. Depending on your version of Android Studio, this may be a RelativeLayout instead. If that is the case, replace the contents of the file with the following:
      android:orientation="vertical" >
        android:text="Hello World"
        tools:context=".BasicMapActivity" />
  3. Add the following markup beneath the <TextView/> tag:
    <!-- Map Fragment embedded with the map object -->

Result: When MapFragment is initialized, your application's BasicMapActivity contains a MapFragment UI element (with the ID mapfragment) that owns a Map object.

Initializing the Map Fragment

When you have defined the basic layout of the application and acquired necessary permissions, the final step is to initialize the instance of the MapFragment class, thus creating and associating a Map with the MapFragment declared in the activity_main.xml file:

  • From the Android View, double-click the file under the java folder to open it for editing.
  • Revise the import statements and functional logic of BasicMapActivity to look like the following:
    import android.os.Bundle;
    public class BasicMapActivity extends Activity {
      // map embedded in the map fragment
      private Map map = null;
      // map fragment embedded in this activity
      private MapFragment mapFragment = null;
      public void onCreate(Bundle savedInstanceState) {
      private void initialize() {
        // Search for the map fragment to finish setup by calling init().
        mapFragment = (MapFragment) getFragmentManager().findFragmentById(;
        mapFragment.init(new OnEngineInitListener() {
          public void onEngineInitializationCompleted(OnEngineInitListener.Error error) {
            if (error == OnEngineInitListener.Error.NONE) {
              // retrieve a reference of the map from the map fragment
              map = mapFragment.getMap();
              // Set the map center to the Vancouver region (no animation)
              map.setCenter(new GeoCoordinate(49.196261, -123.004773, 0.0),
              // Set the zoom level to the average between min and max
              map.setZoomLevel((map.getMaxZoomLevel() + map.getMinZoomLevel()) / 2);
            } else {
              System.out.println("ERROR: Cannot initialize Map Fragment");

Request for Permissions

If your app supports Android 6.0 or above, your app needs to ask users to grant certain permissions at runtime. For more information about this requirement, see Requesting Android Permissions.

Run the Applciation

You can run your simple application by pressing the key combination Shift + F10 (or Ctrl + R on Macs) from within Android Studio. The application renders a map retrieved from the HERE servers. When you are running your application on a device, make sure a data connection is enabled.

See the BasicMapSolution folder for a completed example. You need to add your own App_Id and App_Code for this completed example to work.