Getting started with MapKit for Android

This tutorial explains how install and setup MapKit library and create a map with a placemark for a specific location.

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. Add the MapKit library to your project

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

Create a new project or open an existing one, for example, in Android Studio.
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/"
    }
}
```

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.1.0-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.1.0-full'
}

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. Provide the API key to MapKit

The MapKit SDK requires you to set up the API key in the MapKitFactory.setApiKey method.

We recommend doing that in your Application.onCreate method:

override fun onCreate() {
    super.onCreate()
    MapKitFactory.setApiKey("YOUR_API_KEY")
}

If you don't want to put your API key under a version control system, you can read it from the local.properties file using the BuildConfig class:

Open or create the project's local.properties file. Add the following property with your API key value in place of the YOUR_API_KEY placeholder:
```
MAPKIT_API_KEY=YOUR_API_KEY
```
Note

Make sure your local.properties file is ignored by your VCS.

Open the project's build.gradle file. Add the code for the loading API key from the local.properties file:

ext {
    mapkitApiKey = getMapkitApiKey()
}

private String getMapkitApiKey() {
    def properties = new Properties()
    project.file("local.properties").withInputStream { properties.load(it) }
    return properties.getProperty("MAPKIT_API_KEY", "")
}

In the application's build.gradle file, enter the loaded API key value mapkitApiKey in the field of the BuildConfig:

defaultConfig {
    // ...

    buildConfigField "String", "MAPKIT_API_KEY", "\"${mapkitApiKey}\""
}

Finally, set your API key in MapKitFactory using the BuildConfig.MAPKIT_API_KEY field:

override fun onCreate() {
    super.onCreate()
    MapKitFactory.setApiKey(BuildConfig.MAPKIT_API_KEY)
}

Step 4. Add the map

Add the MapView to your Activity layout:

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

To initialize the MapKit library, call the MapKitFactory.initialize method in Activity.onCreate. Create a private mapView: MapView property.

private lateinit var mapView: MapView

override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    MapKitFactory.initialize(this)
    setContentView(R.layout.activity_main)
    mapView = findViewById(R.id.mapview)
}

Warning

The MapKitFactory.initialize(Context) call loads the MapKit's required native libraries.

Send onStart and onStop events to MapKitFactory and MapView by overriding the Activity.onStart and Activity.onStop methods for the Activity:
```
override fun onStart() {
    super.onStart()
    MapKitFactory.getInstance().onStart()
    mapView.onStart()
}

override fun onStop() {
    mapView.onStop()
    MapKitFactory.getInstance().onStop()
    super.onStop()
}
```
Otherwise, MapKit will be not able to display the map and will stop processing it when the Activity with the map becomes invisible to users.

Build and run your application. There's an example of the Activity with the tappable map:

Map with the smallest zoom

Maps support multiple actions by default: move, rotate, change the zoom, and tilt.

Without additional setup, the map will be shown with the smallest possible zoom for the user's screen.

To change a map's position or zoom, use the Map.move method:

override fun onCreate(savedInstanceState: Bundle?) {
    // ...
    map.move(
        CameraPosition(
            Point(25.1982, 55.272758),
            /* zoom = */ 17.0f,
            /* azimuth = */ 150.0f,
            /* tilt = */ 30.0f
        )
    )
}

The Map.move call accepts the CameraPosition argument, which fully defines the map's position, zoom, tilt, and azimuth.

There's an example of the Activity after applying the move to the map:

Map after applied move

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:

val cameraListener = CameraListener { _, _, _, _ ->
    // ...
}
mapView.mapWindow.map.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.

Step 6. Display a placemark on the map

Let's modify the application such that you can show a tappable placemark on the map.

Add a png resource for the placemark image to the project.

For example, we have the image, and it is accessible by the R.drawable.ic_pin identificator.

Add the placemark for the Map.getMapObjects collection to the specific location.

Use ImageProvider.fromResource to create an ImageProvider instance to get placemark image.

override fun onCreate(savedInstanceState: Bundle?) {
    // ...
    val imageProvider = ImageProvider.fromResource(this, R.drawable.ic_pin)
    val placemark = mapView.map.mapObjects.addPlacemark().apply {
        geometry = Point(25.1982, 55.272758)
        setIcon(imageProvider)
    }
}

To subscribe to created placemark's taps use MapObject.addTapListener method.

private val placemarkTapListener = MapObjectTapListener { _, point ->
    Toast.makeText(
        this@MainActivity,
        "Tapped the point (${point.longitude}, ${point.latitude})",
        Toast.LENGTH_SHORT
    ).show()
    true
}

override fun onCreate(savedInstanceState: Bundle?) {
    // ...
    placemark.addTapListener(placemarkTapListener)
}

Build and run your application. There's a placemark with your custom image on the map. Tap the placemark, and the message toast will show up:

Map after placemark was tapped

Getting started with MapKit for Android

Step 1. Get the MapKit API keyStep 1. Get the MapKit API key

Step 2. Add the MapKit library to your projectStep 2. Add the MapKit library to your project

Step 3. Provide the API key to MapKitStep 3. Provide the API key to MapKit

Step 4. Add the mapStep 4. Add the map