Porting Google Maps v2 to HERE Maps

This porting guide introduces HERE reference library for Google Maps Android API v2, which provides a replacement library project and a set of wrapper APIs that allow Android developers to easily migrate their existing Google Maps applications to use HERE Maps. Before you start porting, please make sure that you have fulfilled all the prerequisites described here.

Note: If you want to use both Google Maps and HERE Maps in the same APK file and select correct maps on runtime, check One APK guide. This applies also, if you are using other services (like AdMob) that Google Play Services library is providing.

This guide assumes that you have an existing Android application that uses the Google Maps Android API v2. You can also use the map sample that comes with Google Play Services SDK to try the instructions presented in this porting guide on a smaller code base and generally explore the functionality of HERE Maps.

Supported version

The HERE reference library for Google Maps Android API v2 currently supports applications that were created using Google Maps Android API v2 Revision published on January 2014 or earlier.

Developers using later revisions of the Google Maps v2 APIs may notice some unavailable functionality.

On top of the issues arising from revision changes, there are also some known issues with the wrapper API, and the following list summarises them:

com.google.android.gms.location.LocationClient * setMockLocation and setMockMode are stubs and do nothing. * addGeofences and removeGeofences are stubs and directly call the provided listener with LocationStatusCodes.GEOFENCE_NOT_AVAILABLE.

com.google.android.gms.common.GooglePlayServicesUtil * getOpenSourceSoftwareLicenseInfo returns empty string. * isGooglePlayServicesAvailable always returns ConnectionResult.SUCCESS.

com.google.android.gms.maps.GoogleMap * animateCamera durationMs parameter doesn't do anything. * OnMarkerDragListener.onMarkerDragStart is never called.

com.google.android.gms.maps.model.Circle com.google.android.gms.maps.model.Polygon com.google.android.gms.maps.model.Polyline com.google.android.gms.maps.model.GroundOverlay com.google.android.gms.maps.model.TileOverlay * Z-index: v2 API uses floats for z-index, the HERE z-index is 16-bit integer. Therefore the range and precision are different and might cause unwanted behavior.

com.google.android.gms.maps.model.Polygon * It's possible to specify holes for the Polygon, but the holes are not drawn.

com.google.android.gms.maps.model.TileOverlay * fadeIn is not supported.

Step 1. Modifying the manifest file

You need to make some minor modifications to the AndroidManifest.xml file of your project to enable HERE Maps. First, specify the application version compatibility by adding or editing the following tag:

    <uses-sdk android:minSdkVersion="11" android:targetSdkVersion="16" />

Add the additional permissions required by HERE:

    <uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />

Within the <application></application> block of tags, add the following library:

    <uses-library android:name="com.here.android" android:required="false" />

All applications using HERE API must have a valid application ID (app ID) and application token (app token). See here how to obtain these. Once you have acquired the app ID and token, insert them within the <application></application> block of tags:

    <meta-data android:name="com.here.android.maps.appid" android:value="YOUR ID" />
    <meta-data android:name="com.here.android.maps.apptoken" android:value="YOUR TOKEN" />

Replace the YOUR ID and YOUR TOKEN strings with the appropriate credentials for your application.

HERE Maps require OpenGL and GPU, so make sure you have OpenGL ES 2.0 usage declared in the manifest file:

    <uses-feature android:glEsVersion="0x00020000" android:required="true" />

In addition, either the whole application or the activity using maps needs to have property android:hardwareAccelerated set true:

    <application ... android:hardwareAccelerated="true">


<manifest ... >
    <uses-sdk android:minSdkVersion="11" android:targetSdkVersion="16" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.INTERNET" />
    <!-- External storage for caching -->
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <!-- My location -->
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
    <!-- Addition permissions required by HERE Maps -->
    <uses-permission android:name="android.permission.CHANGE_NETWORK_STATE" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <!-- Maps API needs OpenGL ES 2.0 -->
    <uses-feature android:glEsVersion="0x00020000" android:required="true" />
    <application ... android:hardwareAccelerated="true">
        <!-- HERE API requires this uses-library definition to work -->
        <uses-library android:name="com.here.android" android:required="true" />
        <activity ... >
            Application ID and token. Note that the values here are just for
            show and will not work. You need to obtain your own personal keys
            for HERE Maps.
        <meta-data android:name="com.here.android.maps.appid" android:value="423897-a9a2c4d8bb4f9b2ec8e3" />
        <meta-data android:name="com.here.android.maps.apptoken" android:value="HRtU5_TgBsKjQP7pbiVYIc" />

Step 2. Import and replace the project library

To begin, you must first import the HERE reference library for Google Maps Android API v2 and replace the Google Play Services library project (google-play-services_lib). For more information about the Google Play Services library project, check the Android developer documentation.

Follow these steps to import the v2 Reference project library:

  1. Ensure that the Nokia X services SDK has been successfully installed on your development environment by inspecting the <Android SDK installation path>/add-ons directory.
  2. From Eclipse, click on File > Import...
  3. On the Import dialog box, select Existing Android Code Into Workspace under the Android folder.
  4. Browse to the library project located at <android-sdk-path>\extras\nokia\nokia_x_services\libs\here\reference_v2_lib.
  5. Check the Copy projects into workspace checkbox and click Finish (see figure 1).

    Figure 1. Importing the reference library.

    Figure 1. Importing the reference library.

  6. From the Package Explorer, right click on reference_v2_lib, then Properties.
  7. In the new dialog box, select the Android tab, and ensure that the library is using "Android 4.1.2" as its build target. The Is Library checkbox should also be checked (see figure 2).

    Figure 2. Setting the library properties including the build target.

    Figure 2. Setting the library properties including the build target.

Once the reference library project has been copied to your workspace, the next step is to configure your application to reference this project:

  1. From Eclipse, right-click on your project and select Properties, then select Android tab.
  2. Under the Project Build Target section, select "Android 4.1.2".
  3. If you had the Google Play Services library referenced, navigate under the Library section, select google-play-services_lib and click Remove.
  4. Click on the Add... button and select the reference-v2_lib project, then click OK. You should now see "reference-v2_lib" in the library list as a reference (see figure 3).

    Figure 3. V2 library referenced in project properties.

    Figure 3. V2 library referenced in project properties.

  5. In the same Properties dialog, select Java Build Path from the left pane.
  6. Under the Order and Export tab, ensure that Android Private Libraries is selected (see figure 4). This ensures that the HERE JAR is packaged as part of your application.

    Figure 4. Android Private Libraries exported.

    Figure 4. Android Private Libraries exported.

  7. Click on the OK button to close the Properties dialog.
  8. From the Eclipse menu, click on Project. Initiate Clean and then build the project to ensure that your project is updated with the latest changes.

Checking other support libraries

If your existing application requires the Android Support Library (e.g. android-support-v4.jar), ensure that the relevant JAR file is also present in your ported project, and it is marked to be exported under Properties > Java Build Path > Order and Export (see figure 5). For instance, the Google Play Services map sample uses FragmentActivity class, which requires version 4 Android support library (android-support-v4.jar) to be linked to the project.

Figure 5. Support library exported.

Figure 5. Support library exported.

Step 3. Run and test your application

Your application will now use HERE Maps instead of Google Maps. There should be no need to make additional changes to the source code of your app. If you still have problems with the application after following the previous steps, make sure that:

  • If you are running the app in the emulator, the use of host GPU is enabled in the Android Virtual Device (AVD) settings and you have a SD card defined.
  • Your internet connection is working and proxy is properly set if needed.
  • Your app ID and token are valid.

Video: Porting to HERE Maps (Google Maps v2)

The media player is loading...

Last updated 12 August 2014

Back to top