Skip to content

Map Compass

In this guide you will learn how to render an interactive map, showing a compass, which points toward the geographic north direction when the map is rotated and the map compass feature is activated. The map is fully 3D, supporting pan, pinch-zoom, rotate and tilt.


First, get an API key token, see the Getting Started guide.
Download the Maps & Navigation SDK for Android archive file

Download the MapCompass project archive file or clone the project with Git

See the Configure Android Example guide.

Run the example

In Android Studio, from the File menu, select Sync Project with Gradle Files

An android device should be connected via USB cable.
Press SHIFT+F10 to compile, install and run the example on the android device.

Map compass example Android screenshot

Map compass example Android screenshot

Press the green button to activate the compass.
The compass arrow reorients to show the geographic north direction.

Map compass example Android screenshot

Map compass example Android screenshot

Rotate the device and the compass arrow reorients again to show the geographic north direction.
Press the red button to deactivate the compass.

How it works

Android example screenshot

You can open the MainActivity.kt file to see how the map compass works.

 1override fun onCreate(savedInstanceState: Bundle?) {
 2     super.onCreate(savedInstanceState)
 3     setContentView(R.layout.activity_main)
 5     surfaceView = findViewById(
 6     compass = findViewById(
 7     btnEnableLiveHeading = findViewById(
 9     // start stop btn
10     buttonAsStart(this, btnEnableLiveHeading)
12     btnEnableLiveHeading.setOnClickListener {
13         isLiveHeadingEnabled.set(!isLiveHeadingEnabled.get())
14         if (isLiveHeadingEnabled.get()) {
15             buttonAsStop(this, btnEnableLiveHeading)
16         } else {
17             buttonAsStart(this, btnEnableLiveHeading)
18         }
19         Toast.makeText(
20             this, "Live heading update, enabled=$isLiveHeadingEnabled ",
21             Toast.LENGTH_SHORT
22         ).show()
23         GemCall.execute {
24             if (isLiveHeadingEnabled.get()) {
25                 startLiveHeading()
26             } else {
27                 stopLiveHeading()
28             }
29         }
30     }
The MainActivity overrides the onCreate function which defines the
buttonAsStart / buttonAsStop button used to turn the compass on or off, as well as color the button green / red, respectively, and a listener for that button, btnEnableLiveHeading.setOnClickListener.
The button listener calls startLiveHeading() or stopLiveHeading() to start or stop reading the live compass sensor data from the device, by adding or removing a listener to the compass data source.
 1private fun startLiveHeading() = GemCall.execute {
 2  dataSource = DataSourceFactory.produceLive()
 4  // start listening for compass data
 5  dataSource?.addListener(object : DataSourceListener() {
 6    override fun onNewData(dataType: EDataType) {
 7      GemCall.execute {
 8        dataSource?.getLatestData(dataType)?.let {
10          // smooth new compass data
11          val heading = headingSmoother.update(CompassData(it).heading)
13          // update map view based on the recent changes
14          surfaceView.mapView?.preferences?.rotationAngle = heading
15        }
16      }
17    }
18  }, EDataType.Compass)
The compass data source listener, when active, reads the compass sensor, smoothed into an average of several readings, and passes this heading to the mapView to rotate the map accordingly, when the device is rotated.
1private fun stopLiveHeading() = GemCall.execute {
2    dataSource?.release()
3    dataSource = null
The red stop button removes the compass sensor data source listener, thus the heading is no longer updated and the map stops rotating when the device is rotated.

Android Examples

Maps SDK for Android Examples can be downloaded or cloned with Git