Take advantage of the new Basemaps styles services v2 (beta) using the ArcGIS Maps SDKs for Native Apps

DonKemlage · ‎06-05-2023

Take advantage of the new Basemaps styles services v2 (beta) using the ArcGIS Maps SDKs for Native Apps

Right now you can be on the forefront of using the latest (and coolest) basemaps in your app built with the ArcGIS Maps SDKs for Native Apps (aka Native SDKs). If this is of interest to you, check out the new ArcGIS REST APIs Basemap styles service v2 (beta) or its announcement.

The Basemap styles service v2 (beta) (aka v2 (beta) services) provides dozens of ready to use styles such as: streets and navigation; topography and imagery; reference; and creative. The service also contains a number of brand new styles, such as ArcGIS Outdoor and OSM Navigation, that you can't access using the existing Native SDKs - and you can even select the language to use for localized place labels. Like the existing v1 service, the v2 (beta) services can also access custom styles stored in ArcGIS.

We anticipate adding future Native SDKs support for the new service using existing API such as the `BasemapStyle` enum that was introduced at version 100.10 - but for now you can access the v2 (beta) services via JSON requests. Since this JSON request pattern of programming may be new to some Native SDK developers, I will show you an example of the steps needed along with some Qt/C++ code using the ArcGIS Maps SDK for Qt to display a v2 (beta) basemap. By the way you could also use the .NET, Kotlin, and Java Native SDKs as well to access the v2 (beta) basemap (the Swift SDK has a bug that we'll fix for the next release). The way you perform a network request is different for each SDK but the general process is the same. If you are into JavaScript development, you can also see a code example for using the v2 (beta) services in the document Basemap layers.

EXAMPLE:

The first thing you need to do is decide what v2 (beta) basemap services you want to try. The Basemap styles service v2 (beta) page has links to each of the styles that you can use and provides the Url needed to access the services. In general, the syntax for the Url follows the pattern of:

https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/webmaps/arcgis/{style}

The second thing you need is an API Key to access the v2 (beta) services. You can get a free API Key for testing via the ArcGIS Developers Dashboard.

The third thing to do is create your app. Using Qt Creator, create a new project and choose the ArcGIS Maps SDK 200.1.0 Qt Quick C++ app template. Name your project BasemapV2 and specify the various configurations you normally use to create a project. Tip: I typically use qmake for my build system.

In the BasemapV2.h file, the class references needed for JSON requests (do this right after the line of code `Q_MOC_INCLUDE("MapQuickView.h")`:

// Class references needed for JSON network requests
class QNetworkAccessManager;
class QNetworkReply;

Also in the BasemapV2.h file, add the following code in the `private` section:

void useBasemapV2(QString& theApiKey, QUrl& theRequestUrl);

// Forward declare member variables used to create the web request
QNetworkAccessManager* m_networkAccessManager = nullptr;
QNetworkReply* m_networkReply = nullptr;

In the main.cpp file, insert the string with your API Key for the line:

const QString apiKey = QString("");

In the BasemapV2.cpp file, add the following #include statements:

#include <QNetworkAccessManager>
#include <QNetworkReply>
#include <QUrl>

Continuing in the BasemapV2.cpp file, modify the constructor argument from `QObject(parent),
m_map(new Map(BasemapStyle::ArcGISStreets, this))` to:

QObject(parent),
m_map(new Map(BasemapStyle::ArcGISStreets, this)),
m_networkAccessManager(new QNetworkAccessManager(this))

Continuing in the BasemapV2.cpp file, look for the `BasemapV2::setMapView(MapQuickView* mapView)` function that was created from the template, find the line of code `m_mapView->setMap(m_map);` and replace it with:

    // Supply your ArcGIS Maps SDK API Key
    // An API Key can be obtained at: https://developers.arcgis.com/dashboard/
    QString v2BasemapApiKey = "YOUR_API_KEY";

    // Specify the Url for one of the ArcGIS REST API Basemap styles services v2 (beta) available
    // See the ArcGIS REST documentation: https://developers.arcgis.com/rest/basemap-styles/
    QUrl v2BasemapQueryUrl{"https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/webmaps/arcgis/outdoor"};

    // Call the function to display the Basemap styles services v2 (beta) in the map view
    useBasemapV2(v2BasemapApiKey, v2BasemapQueryUrl);

NOTE: you need to specify your API Key again for the JSON request.

Finally in the BasemapV2.cpp file, add the following code to the end of the file:

// Function to display the Basemap styles services v2 (beta) in the map view
void BasemapV2::useBasemapV2(QString& theApiKey, QUrl& theRequestUrl)
{
    // Encode the Url web request
    QUrl v2BasemapEncodedUrl{theRequestUrl.toEncoded()};

    // Generate the network request
    QNetworkRequest v2BasemapRequest{v2BasemapEncodedUrl};

    // Set the header for the web request (it will include your ArcGIS Maps SDK API Key)
    v2BasemapRequest.setRawHeader(QByteArray("Authorization"), "Bearer " + theApiKey.toUtf8());

    // Obtain the network reply from the web request
    m_networkReply = m_networkAccessManager->get(v2BasemapRequest);

    // Use an in-line signal to handle when the network reply is finished
    connect(m_networkReply, &QNetworkReply::finished, this,[this]()
            {
                // Read the response from the network reply
                auto v2BasemapResponseByteArray = m_networkReply->readAll();

                // Convert the response to JSON
                QString v2BasemapWebmapJson = v2BasemapResponseByteArray;

                // Create a new map from the JSON
                auto newMap = Map::fromJson(v2BasemapWebmapJson, this);

                // Set the map for the map view
                m_mapView->setMap(newMap);
            });
}

When you run your app you will see the beautiful new ArcGIS Outdoor style basemap displayed.

You can also experiment with supplying a particular language parameter to your Url to have your map display the language of your choice for the labeled features in the service. For example, using our previous Url based on the ArcGIS Outdoors style basemap, if you wanted to have the map display the local language for place names as you zoom into different parts of the world, you could append `?language=local` to the end of the Url:

https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/webmaps/arcgis/outdoor?language=local

I hope this information helps you to be an early adopter of the Basemaps styles services v2 (beta) and adds some new excitement to your app development.

And one more thing, we also have another beta program that you can use right now for place services. You can find more about this in the blog post, Announcing the new places service for developers (beta release).

Happy Day!
-don