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 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 styles 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.
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 ArcGIS Runtime and several StreetMap Premium extensions when the app initializes. To update these license strings when they expire, you will need to update and recompile the app code.
// Define the QStringList of ArcGIS Maps SDK extensions.
QStringList extensions;
extensions.append(m_smpKeyNorthAmerica);
extensions.append(m_smpKeyLatinAmerica);
extensions.append(m_smpKeyEurope);
// Set the ArcGIS runtime environment license using an API Key access token and the QString list of extensions.
const LicenseResult resultLicense = ArcGISRuntimeEnvironment::setLicense(m_appLicenseKey, extensions);
You could also read license strings on startup from a text file included with the app and set the licenses. This would allow the user to update license strings in a separate file and would eliminate the need for you to update and recompile the app code.
// The following code reads license strings from a text file into a QStringList called licenseStrings.
// Variable to store the (one) ArcGIS Runtime license string.
QString runtimeLicense;
// Variable to store the extension license strings (all others in the file).
QStringList extensionLicenses;
for (const QString& s : licenseStrings)
{
// See if it's an ArcGIS Runtime license string.
if (s.startsWith("runtimelite") ||
s.startsWith("runtimebasic") ||
s.startsWith("runtimestandard") ||
s.startsWith("runtimeadvanced"))
{
// Store the key.
runtimeLicense = s;
}
else
{
// Add the license string to the QStringList.
extensionLicenses.append(s);
}
}
// Set the licenses before using any ArcGIS Runtime objects.
LicenseResult licenseResult = ArcGISRuntimeEnvironment::setLicense(runtimeLicense, extensionLicenses);
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.
// Obtain a license from the static ArcGIS Runtime environment object.
License* license = ArcGISRuntimeEnvironment::license();
// Obtain the QList of extenstion licenses from the license.
const QList extensionLicenses = license->extensions();
// Loop thru the extension liceneses.
for (const ExtensionLicense &license : extensionLicenses)
{
// Get the name of the extension license.
const QString name = license.name();
// Get the expiration date of the extension license.
const qint64 expiry = license.expiry().toMSecsSinceEpoch();
// Get todays date.
const qint64 now = QDateTime::currentMSecsSinceEpoch();
// Display the extension license expiration date and todays date.
qDebug() << "expiry:" << expiry << ", now:" << now;
// Determine how many days between the exipration date and now.
const long daysLeft = (expiry - now) / 1000 / 60 / 60 / 24;
// Display the number of days lest if less than 1000 days away.
if (daysLeft <= 1000)
qDebug() << "Days left until " << name << " expires: " << daysLeft;
}
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.
// Test if the path to the mobile map package exists.
if (QFile::exists(m_pathToPackage))
{
// Create a new mobile map package from the path.
m_mmpk = new MobileMapPackage(m_pathToPackage, this);
// Test of the mobile map package successfully loads.
if (m_mmpk && m_mmpk->loadStatus() == LoadStatus::NotLoaded)
{
// Signal to execute when the mobile map package is done loading.
connect(m_mmpk, &MobileMapPackage::doneLoading, this, [this]()
{
// Access first map in mobile map package.
m_map = m_mmpk->maps().at(0);
// Add the mobile map package to the map.
m_mapView->setMap(m_map);
});
// Call the mobile map package load event.
m_mmpk->load();
}
}
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.
// Get the locator task from the mobile map package.
m_locatorTask = m_mmpk->locatorTask();
// Call the geocode function on the locator task using the input string to be geocoded.
m_locatorTask->geocodeAsync("Indianapolis Motor Speedway").then(this, [this](const QList<GeocodeResult>& geocodeResults)
{
// Get the geocode result from the first one in the list of geocode results.
const GeocodeResult result = geocodeResults.at(0);
// Zoom the map to the extent of the geocode result.
m_mapView->setViewpointGeometryAsync(result.extent());
});
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.
The following example gets a TransportationNetworkDataset from a map in the StreetMap Premium package, then uses it to create a new RouteTask.
void RouteAndDirections::createRouteTask()
{
// Get the map from the map view.
Map* map = m_mapView->map();
// Get the QList of transportation network datasets from the map.
QList<TransportationNetworkDataset*> transportationNetworkDatasets = map->transportationNetworks();
// Get the first the transportation network dataset from the QList of transportation network datasets.
TransportationNetworkDataset* streetNetwork = transportationNetworkDatasets.at(0);
// Create a new route task from the street transportation network dataset.
m_routeTask = new RouteTask(streetNetwork, this);
// Signal to execute when the route task is done loading.
connect(m_routeTask, &RouteTask::doneLoading, this, [this]()
{
// Call the custom createDefaultRouteParameters function.
createDefaultRouteParameters();
});
// Call the route task load event.
m_routeTask->load();
}
void RouteAndDirections::createDefaultRouteParameters()
{
// Call the create default parameters function on the route task.
m_routeTask->createDefaultParametersAsync().then(this, [this](const RouteParameters& defaultParameters)
{
// Call the custom startSolveRouteTask function using the route parameters.
startSolveRouteTask(defaultParameters);
});
}
void RouteAndDirections::startSolveRouteTask(RouteParameters defaultParameters)
{
// Set the QList of stops on the route parameters.
defaultParameters.setStops(m_stops);
// Signal to execute when the route task has an error.
connect(m_routeTask, &RouteTask::errorOccurred, this, [](const Error error)
{
// Display the error.
qDebug() << "RouteTask solveRoute returned an error: " << error.message() << ": " << error.additionalMessage();
});
// Call the solve route function on the route task using the route parameters.
m_routeTask->solveRouteAsync(defaultParameters).then(this, [this](const RouteResult routeResult)
{
// Call the custom processRouteResult function using the route result.
processRouteResult(routeResult);
});
}
void RouteAndDirections::processRouteResult(const RouteResult& routeResult)
{
// Test if the route result is valid.
if (!routeResult.isEmpty())
{
// Get the QList of routes from the route result.
const QList<Route> routes = routeResult.routes();
// Get the first route from the QList of routes.
const Route route = routes.at(0);
// Get the graphics overlay list model from the map view.
GraphicsOverlayListModel* graphicsOverlayListModel = m_mapView->graphicsOverlays();
// Get the first graphics overlay from the graphics overlay list model.
GraphicsOverlay* graphicsOverlay = graphicsOverlayListModel->at(0);
// Get the graphics list model from the graphics overlay.
GraphicListModel* graphicsListModel = graphicsOverlay->graphics();
// Get the first graphic from the graphics list model.
Graphic* graphic = graphicsListModel->at(0);
// Set the geometry on the graphic to that of the route's geometry.
graphic->setGeometry(route.routeGeometry());
}
}