StreetMap Premium for ArcGIS Runtime provides enriched street data, which powers a high-quality cartographic maps and high-quality search, geocoding, and route analysis. StreetMap Premium maps are consistent across all regions of the world and can be taken offline for disconnected use; they can simultaneously fulfill the need for an address locator, street network dataset, and basemap in your app.
StreetMap Premium delivers data from HERE Technologies as a mobile map package (an .mmpk file) for your app to access locally. This format allows the data to be accessed offline (without a network connection, in other words) and therefore doesn't consume data from your user's data plan. This is the same high-quality data used by ArcGIS Online services, including the Geocoding service, Routing service, and Basemap layer service. Instead of spending your time putting together such datasets yourself, you can focus on developing apps that provide advanced searching, geocoding, and routing analysis offline.
StreetMap Premium data is organized into regions that are licensed as extensions and are downloaded individually (North America, Latin America, Europe, the Middle East, Africa, and Asia Pacific), allowing your apps to provide a consistent user experience across the globe. Within these regions, maps are available at the sub-region, country, or state/province level. You can even use ArcGIS Pro to clip the data to a custom area of interest.
How to add StreetMap Premium data
Follow these general steps to use StreetMap Premium in your app.
-
Download the StreetMap Premium Greater Los Angeles mobile map package that is provided for development and testing. When you're ready to deploy your app, you'll need to download the required StreetMap Premium packages from My Esri and license StreetMap Premium for each extension (region) your app uses.
-
Provide the data (mobile map package) for your app. You can provide package(s) with your app or allow the user to download them as needed. Once the package (
*.mmpk) is available on the client, you can open it to retrieve data, maps, and locators. Using the contents of the package, you can:- Display StreetMap Premium data in your app.
- Locate addresses and places using a StreetMap Premium locator task.
- Solve routes using the transportation network dataset provided in the StreetMap Premium map package.
-
Attribute StreetMap Premium data somewhere in the app user interface using the words
mapping data from HERE. If you're attributing more than one data provider, the HERE attribution cannot be less prominent than the attribution for the other data providers. See Attribution in your app for more information.
License StreetMap Premium
Each StreetMap Premium region is licensed as an extension. A StreetMap Premium extension license works with all license levels: Lite, Basic, Standard, and Advanced. Unlike other extension licenses, this license does not unlock API capabilities, but rather licenses the use of StreetMap Premium data within one of the available regions. For each region you license, you receive a license string to use in your app. These licenses are good for one year, so you must provide a mechanism to notify your users and update the license string for your app when (or before) the license expires.
The following code licenses your app and several StreetMap Premium extensions when the app initializes. To update these license keys when they expire, you will need to update and recompile the app code.
// ArcGIS Maps license key
val arcgisLicenseString = "runtimelite,1000,rudxxxxxxxxx,28-feb-2023,xxxxxxxxxxxxxxxxxxxx"
val arcgisLicenseKey = LicenseKey.create(arcgisLicenseString) as LicenseKey
// Extension license keys for various StreetMap Premium areas
val smpNorthAmericaString = "runtimesmpna,1000,rudxxxxxxxxx,13-mar-2023,xxxxxxxxxxxxxxxxxxxx"
val smpLatinAmericaString = "runtimesmpla,1000,rudxxxxxxxxx,13-mar-20123,xxxxxxxxxxxxxxxxxxxx"
val smpEuropeString = "runtimesmpe,1000,rudxxxxxxxxx,16-dec-2023,xxxxxxxxxxxxxxxxxxxx"
val smpNorthAmericaKey = LicenseKey.create(smpNorthAmericaString) as LicenseKey
val smpLatinAmericaKey = LicenseKey.create(smpLatinAmericaString) as LicenseKey
val smpEuropeKey = LicenseKey.create(smpEuropeString) as LicenseKey
// Add StreetMap Premium license keys to an array
val extensionKeyList = listOf(smpNorthAmericaKey, smpLatinAmericaKey, smpEuropeKey)
// Set the license for ArcGIS Runtime and the three extensions (areas)
ArcGISEnvironment.setLicense(arcgisLicenseKey, extensionKeyList)
You could also read license keys on startup from a text file included with the app and set the licenses. This would allow the user to update license keys in a separate file and would eliminate the need for you to update and recompile the app code.
// ... code here to read a file that has one runtime license string and some extension license strings ...
// Stores ArcGIS Maps SDK license key
var runtimeLicenseKey: LicenseKey? = null
// Loop through license keys from file
for (license: String in licenseStringsReadFromFile) {
// Check if it is a Runtime license key
if (license.startsWith("runtimelite") ||
license.startsWith("runtimebasic") ||
license.startsWith("runtimestandard") ||
license.startsWith("runtimeadvanced")
) {
// Store license key
runtimeLicenseKey = LicenseKey.create(license)
} else {
extensionKeyList.add(LicenseKey.create(license) as LicenseKey)
}
}
Log.i(localClassName, "runtimeLicenseKey: " + runtimeLicenseKey.toString())
Log.i(localClassName, "extensionKeyList: " + extensionKeyList.toString())
// Set license using license key and any extension licenses
ArcGISEnvironment.setLicense(runtimeLicenseKey as LicenseKey, extensionKeyList)
As the licenses in your app near expiration, you might want to notify the user that new licensing information will be required soon.
The following code loops through all extension licenses for the app and notifies the user if a license is within 10 days of expiring.
// Get the current licensing information
val license: License = ArcGISEnvironment.license
// Get all extension licenses
val extensionLicenses: List<ExtensionLicense> = license.extensions
// Loop through extension licenses and see when each expires
extensionLicenses.forEach { extensionLicense ->
// Get license name and data of expiration
val licenseName: String = extensionLicense.name
val date: Instant = extensionLicense.expiry
// Get number of days till license expires
val timeLeft: Long = date.toEpochMilli() - System.currentTimeMillis()
val millisecondsADay = 1000 * 60 * 60 * 24
val daysLeft = timeLeft / millisecondsADay
// Warn user of days left on license if under 10 days
if (daysLeft <= 10) {
Log.i(localClassName, "Days left till $licenseName expires: $daysLeft")
}
else {
Log.i(localClassName, "More than 10 days until $licenseName expires.")
}
}
Display StreetMap Premium data
Inside each StreetMap Premium mobile map package, you'll find two maps: Navigation Day and StreetMap Day. Each of these maps display the same data and use similar symbology for the layers. They also use scale dependent rendering to improve display performance and readability. The Navigation Day map, however, displays streets with a wider symbol and with more and larger labels, as illustrated in the following image. You can choose the map that best suits the use case, device, screen size, and so on for your app.
The following example opens a StreetMap Premium mobile map package file and displays the Navigation Day map in the app's map view.
// Open a StreetMap Premium mobile map package
val mobileMapPackage = MobileMapPackage(pathToSMPIndianammpk)
lifecycleScope.launch {
mobileMapPackage.load().onSuccess {
if (mobileMapPackage.maps.isNotEmpty()) {
// Get the first map, which is the navigation map
val navigationMap: ArcGISMap = mobileMapPackage.maps[0]
// Add it to the map view
mapView.map = navigationMap
}
}
}
Locate addresses and places
In addition to street data and maps, each StreetMap Premium mobile map package contains a locator task. Use the locator task to geocode addresses, intersections, or places of interest within the area covered by the package.
The following example opens a StreetMap Premium mobile map package file, gets the associated LocatorTask, and uses it to find a location.
// Open a StreetMap Premium mobile map package
val indianaPackage = MobileMapPackage(pathToSMPIndianammpk)
lifecycleScope.launch {
indianaPackage.load().onSuccess {
if (indianaPackage.maps.isNotEmpty()) {
// Get the first map, which is the navigation map
val navigationMap: ArcGISMap = indianaPackage.maps[0]
// Add it to the map view
mapView.map = navigationMap
}
else {
return@onSuccess showError("The mmpk does not contain a map.")
}
val locatorTask = indianaPackage.locatorTask
val geocodeResultList = locatorTask?.geocode("Indianapolis Motor Speedway")?.getOrElse { error ->
return@launch showError("No geocode results returned." + error.message)
}
val sortedGeocodeResultList = geocodeResultList?.sortedByDescending { geocodeResult ->
geocodeResult.score
}
val highestScoreGeocodeResult = sortedGeocodeResultList?.get(0)
val geocodeResultLabel = highestScoreGeocodeResult?.label ?: "No geocode result found."
Log.i(localClassName, "Mobile map package loaded successfully. Label of geocode result is: " + geocodeResultLabel)
// clear graphics overlay of existing graphics
graphicsOverlay.graphics.clear()
Log.i(localClassName, "displayLocation is a point at: " + highestScoreGeocodeResult?.displayLocation?.x + " and " + highestScoreGeocodeResult?.displayLocation?.y)
// create graphic object
val resultLocationGraphic = Graphic(
highestScoreGeocodeResult?.displayLocation,
foundPlaceSymbol
)
mapView.graphicsOverlays.add(graphicsOverlay)
graphicsOverlay.graphics.add(resultLocationGraphic)
if (highestScoreGeocodeResult?.displayLocation != null) {
lifecycleScope.launch {
mapView.setViewpointCenter(highestScoreGeocodeResult.displayLocation as Point, 72000.0)
}
}
else {
showError("The displayLocation property of highestScoreGeocodeResult is null.")
}
}.onFailure {
showError("Mobile map package failed to load.")
}
}
Solve routes
Maps in a StreetMap Premium package have an associated transportation network dataset. You can use this dataset to solve routes between two or more locations in the street network. The maps must be loaded before you can access the transportation dataset it contains.
// Get the (first and only) street network data set from one of the maps in the package
val streetNetwork: TransportationNetworkDataset =
indianaPackage.maps[0].transportationNetworks[0]
// Create a route overlay to display route in a solid, green line of width 5
val routeOverlay = GraphicsOverlay().apply {
renderer = SimpleRenderer(SimpleLineSymbol(SimpleLineSymbolStyle.Solid, Color.red, 5f))
}
// Create a new route task that uses the street network
val routeTask = RouteTask(streetNetwork)
lifecycleScope.launch {
routeTask.load().onSuccess {
// Create two stops and add them to a list
val stops: List<Stop> = listOf(Stop(fromMapPoint), Stop(toMapPoint))
val defaultRouteParameters: RouteParameters =
routeTask.createDefaultParameters().getOrElse { error ->
return@launch showError("Default params for route task were not created.")
}
// Clears any existing stops and sets the one passed
defaultRouteParameters.setStops(stops)
// Solve the route
val solveRoute: RouteResult = routeTask.solveRoute(defaultRouteParameters).getOrElse { error ->
return@launch showError("Error solving route. " + error.message)
}
Log.i(localClassName,"Solved route with ${solveRoute.routes[0].directionManeuvers.size} direction maneuvers.")
if (solveRoute.routes.isNotEmpty()) {
val route = solveRoute.routes[0]
val routeGraphic = Graphic(route.routeGeometry)
routeOverlay.graphics.add(routeGraphic)
mapView.graphicsOverlays.add(routeOverlay)
routeOverlay.extent?.let { extent -> mapView.setViewpointGeometry(extent, 16.0) }
}
}.onFailure { error ->
return@launch showError("Route task failed to load. " + error.message)
}
}
}.onFailure { error ->
return@launch showError("Mobile map package did not load successfully." + error.message)
}
}