MapKit Mobile SDK

Getting started with MapKit for Android

The MapKit library for Android 5.0 and later is available in the Maven Central repository. To create an application with a Mappable map:

Step 1. Get the MapKit API key

Before you can use MapKit SDK in your application, you need the API key.

Go to the Mappable Account and register a new account or log in to an existing. The main page will display a key that is suitable for any Mappable service.

Step 2. Install the MapKit library

The MapKit SDK library for Android 5.0 and later is available in the Maven Central repository.

  1. Create a new project or open an existing one, for example, in Android Studio.

  2. Open the project's build.gradle file. In the repositories section, add the Maven Central and Google Maven repositories:

    repositories {
    ...
    mavenCentral()
    maven {
         url "http://maven.google.com/"
    }
}

  3. Open the application's (module's) build.gradle file. In the dependencies section, add the following dependency:

    dependencies 
{
    // The lite library only contains the map, traffic layer,
    // LocationManager, and UserLocationLayer and lets you download offline maps (in the paid version only).
    implementation 'world.mappable.android:maps.mobile:1.0.2-lite'

    // The full library supplements lite version features with car routing,
    // bike routing, pedestrian routing, and public transport routing,
    // search, suggest, geocoding, and panorama display.
    // implementation 'world.mappable.android:maps.mobile:1.0.2-full'
}

  4. Synchronize the project to apply the changes. For example, in Android Studio, you can click Sync Now or select File → Synchronize from the menu. Wait for synchronization to finish.

If synchronization succeeds, the library is automatically added to the project when it is compiled.

Step 3. Set up the library

  1. Add the map to your Activity:

    <world.mappable.mapkit.mapview.MapView
    android:id="@+id/mapview"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

  2. Set your API key in the onCreate() method of your Application descendant:

    @Override
public void onCreate() {
    super.onCreate();
    MapKitFactory.setApiKey("Your API key");
}

  3. Initialize the map in the onCreate() method of the necessary Activity:

    private MapView mapview;

@Override
protected void onCreate(Bundle savedInstanceState) {

    super.onCreate(savedInstanceState);
    MapKitFactory.initialize(this);

    // Specify the Activity name instead of 'map'.
    setContentView(R.layout.map);
    mapview = (MapView)findViewById(R.id.mapview);
    mapview.getMap().move(
        new CameraPosition(new Point(25.198200, 55.272758), 11.0f, 0.0f, 0.0f),
        new Animation(Animation.Type.SMOOTH, 0),
        null);
}

    Note

    We don't recommend calling MapKitFactory.initialize() in the Application.onCreate() method. This can lead to unnecessary operations and increased battery use.

  4. Send onStart and onStop events to MapKitFactory and mapView. Otherwise, MapKit will not be able to display the map and stop processing the map when the Activity with the map becomes invisible to the user:

    @Override
protected void onStop() {
    mapView.onStop();
    MapKitFactory.getInstance().onStop();
    super.onStop();
}

@Override
protected void onStart() {
    super.onStart();
    MapKitFactory.getInstance().onStart();
    mapView.onStart();
}

Step 4. Build and run the application

When working in Android Studio, you can start the application immediately. The build will be performed automatically. Follow the instructions below to run the app on:

Step 5. Note the following

MapKit stores weak references to the Listener objects passed to it. You need to store references to them in memory yourself:

private final CameraListener cameraListener = new CameraListener() {
    // ...
}  
mapview.getMap().addCameraListener(cameraListener);

Note

By default, the methods of any Listener objects and platform interfaces are called on the main thread unless the method documentation specifies otherwise.

Sample application

package world.mappable.mapkitdemo;

import android.os.Bundle;
import android.app.Activity;

import world.mappable.mapkit.Animation;
import world.mappable.mapkit.MapKitFactory;
import world.mappable.mapkit.geometry.Point;
import world.mappable.mapkit.map.CameraPosition;

import world.mappable.mapkit.mapview.MapView;

/**
* This example shows a map and moves the camera to the specified point. 
* Be sure to request the necessary permissions. 
*/
public class MapActivity extends Activity {
     /**
     * Substitute "your_api_key" with a valid API key.
     * You can get the key at https://mappable.world
     */
    private final String MAPKIT_API_KEY = "your_api_key";
    private final Point TARGET_LOCATION = new Point(25.198200, 55.272758);

    private MapView mapView;

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        /**
        * Set the API key before you initialize MapKitFactory.
        * We recommend setting the key in the Application.onCreate() method,
        * but in this example, it is set in Activity.
        */
        MapKitFactory.setApiKey(MAPKIT_API_KEY);
        /**
        * Initializes the library to load the required native libraries.
        * We recommend initializing the MapKit library in the Activity.onCreate() method.         
        * Initializing it in the Application.onCreate() method may lead to unnecessary calls 
        * and increased battery usage.
        */
        MapKitFactory.initialize(this);
        // Creating a MapView.
        setContentView(R.layout.map);
        super.onCreate(savedInstanceState);
        mapView = (MapView)findViewById(R.id.mapview);

        // Moving the camera to the TARGET_LOCATION point.
        mapView.getMap().move(
                new CameraPosition(TARGET_LOCATION, 14.0f, 0.0f, 0.0f),
                new Animation(Animation.Type.SMOOTH, 5),
                null);
    }

    @Override
    protected void onStop() {
        // Make sure to pass the calls of the onStop method to the MapView and MapKit instances.
        mapView.onStop();
        MapKitFactory.getInstance().onStop();
        super.onStop();
    }

    @Override
    protected void onStart() {
        // Make sure to pass the calls of the onStart method to the MapView and MapKit instances.
        super.onStart();
        MapKitFactory.getInstance().onStart();
        mapView.onStart();
    }
}

The complete sample code is available in the GitHub repository.

In this article: