Apply Map Style

_{Last updated: January 20, 2026 | 3 minutes read}

This example demonstrates how to create an app that displays an interactive map with a non-default style.

Map style with topography

Fetch of Available Map Styles

First, a content store item is defined, so that map styles can be requested from it.

private val contentStore = ContentStore()

Then fetchAvailableStyles() gets the list of map styles available for download from the online content store server.

contentStore.asyncGetStoreContentList() launches the request to get the list.

The onStarted listener is called when the content store service is started, and the list of styles download started.

The onCompleted listener is defined to detect when the list of styles download is complete.

At that point, if the list is not empty, the listener selects the first style (index 0) or the style in the middle of the list (if the list has multiple elements) and starts downloading that style automatically, though in a real-world use case, the user would select which style to download.

MainActivity.ktView on Github

private fun fetchAvailableStyles() = SdkCall.execute {
 // Call to the content store to asynchronously retrieve the list of map styles.
 contentStore.asyncGetStoreContentList(EContentType.ViewStyleHighRes,
     onStarted = {
         progressBar.visibility = View.VISIBLE
         showStatusMessage("Started content store service.")
     },
     onCompleted = onCompleted@{ styles, errorCode, _ ->
         progressBar.visibility = View.GONE
         showStatusMessage("Content store service completed, error code: $errorCode")
         when (errorCode) {
             GemError.NoError -> {
                 if (styles.size == 0) return@onCompleted
                 // The map style items list is not empty
                 // or null so we will select an item.
                 var style = styles[0]
                 if (styles.size > 1) // does it have a middle element?
                     style = styles[(styles.size / 2) - 1]
                 showStatusMessage("Preparing download.", true)
                 startDownloadingStyle(style)
             }
             GemError.Cancel -> {
                 // The action was cancelled.
                 return@onCompleted
             }
             else -> {
                 // There was a problem at retrieving the content store items.
                 showDialog("Content store service error: ${GemError.getMessage(errorCode)}")
             }
         }
     })
}

startDownloadingStyle(style: ContentStoreItem) is the function that the listener calls to download a style from the content store.

Note that the function automatically applies the new map style as soon as the download is complete using the method applyStyle(style).

MainActivity.ktView on Github

private fun startDownloadingStyle(style: ContentStoreItem) = SdkCall.execute {
     val styleName = style.name ?: "NO_NAME"
     // Start downloading a map style item.
     style.asyncDownload(
         onStarted = {
             showStatusMessage("Started downloading $styleName.")
             onDownloadStarted(style)
         },
         onStatusChanged = { status ->
             onStatusChanged(status)
         },
         onProgress = { progress ->
             onProgressUpdated(progress)
         },
         onCompleted = { _, _ ->
             showStatusMessage("$styleName was downloaded. Applying style...")
             applyStyle(style)
             showStatusMessage("Style $styleName was applied.")
             styleContainer.visibility = View.GONE
         }
     )
}

Set the map to use the newly downloaded map style.

MainActivity.ktView on Github

private fun applyStyle(style: ContentStoreItem) = SdkCall.execute {
     // Apply the style to the main map view.
     gemSurfaceView.mapView?.preferences?.setMapStyleById(style.id)
}

Map Display

MainActivity overrides the onCreate() function which calls the fetchAvailableStyles() function to get the list of map styles from the content store on the server.

That function then automatically downloads and then applies a style, as soon as it obtains the list of styles.

MainActivity.ktView on Github

override fun onCreate(savedInstanceState: Bundle?)
{
     super.onCreate(savedInstanceState)
     setContentView(R.layout.activity_main)

     progressBar = findViewById(R.id.progress_bar)
     gemSurfaceView = findViewById(R.id.gem_surface)
     statusText = findViewById(R.id.status_text)
     statusProgressBar = findViewById(R.id.status_progress_bar)
     styleContainer = findViewById(R.id.style_container)
     styleName = findViewById(R.id.style_name)
     downloadProgressBar = findViewById(R.id.download_progress_bar)
     downloadedIcon = findViewById(R.id.downloaded_icon)

     SdkSettings.onMapDataReady = onMapDataReady@{ isReady ->
         if (!isReady) return@onMapDataReady
         fetchAvailableStyles()
     }
}