Display a map (basemap session) | OpenLayers

Learn how to use a basemap session to display a map.

The ArcGIS Basemap Styles serviceThe ArcGIS Basemap Styles service, also referred to as the Basemap Styles service, is a location service that provides basemap styles and data for the world. It returns styles as Mapbox styles and web maps, and data as vector tiles and/or map tiles. It supports all of the styles in the ArcGIS Basemap style and Open Basemap style family. An ArcGIS Location Platform or ArcGIS Online account is required to use the service.Learn more allows you to display basemaps using basemap sessions. A basemap session is a time window (up to 12 hours) during which a single user can access unlimited basemap tiles from the service through one application. This means that instead of being charged for individual tile usage, you are only charged once per session.

In this tutorial, display a map using a basemap session that lasts for 12 hours.

This application will use the basemap session usage model.

Prerequisites

You need an ArcGIS Location Platform account.

ArcGIS Online and ArcGIS Enterprise accounts are not supported.

Steps

Create a new app

Create a new CodePen app with a map div that is the full width and height of the browser window.

Go to CodePen and create a new pen for your application.

In CodePen > HTML, add HTML and CSS to create a page with a div element called map.

Use dark colors for code blocks
<!DOCTYPE html>
<html lang="en">

  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="initial-scale=1, maximum-scale=1, user-scalable=no">
    <title>OpenLayers Tutorials: Display a map</title>

    <style>
    html,
    body,
    #map {
      padding: 0;
      margin: 0;
      height: 100%;
      width: 100%;
      font-family: Arial, Helvetica, sans-serif;
      font-size: 14px;
      color: #323232;
    }
    </style>

  </head>

  <body>
    <div id="map"></div>

  </body>

</html>

Set up authentication

Create a new API key credentialAPI key credentials are an item that contains the parameters used to create and manage long-lived access tokens for API key authentication. They are a type of developer credential.Learn more with the correct privileges to access the resources used in this tutorial.

Go to the Create an API key tutorial and create an API keyAn API key is a long-lived access token created using API key credentials. They are valid for up to one year and are typically embedded directly into client applications.Learn more with the following privilege(s)Privileges are a set of permissions assigned to ArcGIS accounts, developer credentials, and applications that grant access to secure resources and functionality in ArcGIS.Learn more:
- Privileges:
  - Location services > Basemaps
Copy the API key access token to your clipboard when prompted.
Add a <script> element in the HTML <body> and create an accessToken variable to store your access tokenAn access token is an authorization string that provides access to secure ArcGIS content, data, and services. Its capabilities are determined by the privileges it supports. It is obtained by implementing API key authentication, User authentication, or App authentication.Learn more. Set YOUR_ACCESS_TOKEN with the access token you previously copied from your API key credentialsAPI key credentials are an item that contains the parameters used to create and manage long-lived access tokens for API key authentication. They are a type of developer credential.Learn more.
Expand
Use dark colors for code blocks
```
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
    <script>

    /* Use for API key authentication */
    const accessToken = "YOUR_ACCESS_TOKEN";

    </script>
```
Expand

Add script references

You need to add <script> and <link> tags to load the JavaScript and CSS files for OpenLayers and ol-mapbox-style. You also reference the arcgis-rest-basemap-sessions and arcgis-rest-request packages to access the basemap sessions wrapper class.

In the index.html file, add the following <link> and <script> references.

Use dark colors for code blocks
    <!-- Load OpenLayers and OLMS from CDN -->
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/ol@v10.9.0/ol.css">
    <script src="https://cdn.jsdelivr.net/npm/ol@v10.9.0/dist/ol.js"></script>
    <script src="https://cdn.jsdelivr.net/npm/ol-mapbox-style@13.4.1/dist/olms.js"></script>
    <!-- Load ArcGIS REST JS -->
    <script src="https://unpkg.com/@esri/arcgis-rest-request@4/dist/bundled/request.umd.js"></script>
    <script src="https://unpkg.com/@esri/arcgis-rest-basemap-sessions@1/dist/bundled/basemap-sessions.umd.js"></script>

Create a session

To access ArcGIS basemaps, you create a basemap session which can last for up to 12 hours. In this example, the session is set to 12 hours or 43200 seconds. This allows you to access as many basemap tiles as you want for one basemap session charge.

Create an asynchronous function called createBasemapSession to start a new BasemapStyleSession. Set the duration of the session to 43200 seconds (12 hours). Set autoRefresh to false to prevent the session from refreshing automatically.

Expand
Use dark colors for code blocks
    async function createBasemapSession() {
      return await arcgisRest.BasemapStyleSession.start({
        authentication: accessToken,
        styleFamily: "arcgis",
        duration: 43200, // 12 hours in seconds
        autoRefresh: false
      });
    }
Expand

Create a map

Use the session's token to load a basemap style by appending it to the style URL.

Declare the map variable globally so it can be accessed later (e.g., when restarting the session). Set the basemap style to arcgis/outdoor.

Expand
Use dark colors for code blocks
    const basemapStyle = "arcgis/outdoor";
    let map;

Expand

Create a function called loadMap that initializes a map and applies a basemap style URL with a session token. After applying the style, call setAttribution() to ensure the attribution is correctly displayed.

Expand
Use dark colors for code blocks
    async function loadMap(sessionToken) {
      map = new ol.Map({
        target: "map",
        view: new ol.View({
          center: ol.proj.fromLonLat([-20, 30]),
          zoom: 3
        })
      });

      const styleURL = `https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/${basemapStyle}?token=${sessionToken}`;

      olms.apply(map, styleURL).then(() => {
        // Add Esri attribution
        // Learn more in https://esriurl.com/attribution
        const source = map.getLayers().item(0).getSource();
        const poweredByEsriString = "Powered by <a href='https://www.esri.com/en-us/home' target='_blank'>Esri</a> | ";

        const attributionFn = source.getAttributions();
        if (attributionFn) {
          source.setAttributions((ViewStateLayerStateExtent) => {
            return [poweredByEsriString, ...attributionFn(ViewStateLayerStateExtent)];
          });
        } else source.setAttributions(poweredByEsriString);
      });
    }
Expand

Define an initApp function to create the basemap session and pass its token into loadMap. Call this function when the app starts.

Expand
Use dark colors for code blocks
    let basemapSession;

    async function initApp() {
      basemapSession = await createBasemapSession();

      await loadMap(await basemapSession.getToken());
    }

    initApp();
Expand

Handle session expiration

To ensure your basemap always uses a valid session token, listen for basemap session events. You can refresh credentials when the session expires, and update the basemap layer URLs when the session is refreshed.

Listen for the expired and refreshed events from the session. When the session expires, call refreshCredentials. When the session is refreshed, call applyToken to update all layer URLs with the new token. You will create the applyToken function in the next step.

Expand
Use dark colors for code blocks
    let basemapSession;

    async function initApp() {
      basemapSession = await createBasemapSession();

      basemapSession.on("expired", () => {
        basemapSession.refreshCredentials();
      });

      basemapSession.on("refreshed", (e) => {
        applyToken(e.previous.token, e.current.token);
      });

      await loadMap(await basemapSession.getToken());
    }

    initApp();
Expand

Create a function called applyToken that updates the URLs of all map layers to use the new session token.

Expand
Use dark colors for code blocks
    function applyToken(oldToken, newToken) {
      map.getLayers().forEach((layer) => {
        const source = layer.getSource();

        if (source.getUrls) { // Source contains multiple URLs
          const urls = source.getUrls();
          if (urls.some((url) => url.includes(oldToken))) {
            source.setUrls(urls.map((url) => url.replace(oldToken, newToken)));
          }
        } else if (source.getUrl) { // Source contains a single URL
          const url = source.getUrl();
          if (url && url.includes(oldToken)) {
            source.setUrl(url.replace(oldToken, newToken));
          }
        }
      });
    }
Expand

Run the app

Run the app.

The app should display the arcgis/outdoor style from the Basemap Styles service using a basemap session. When the basemap session expires, the app refreshes the session and updates the layer URLs with the new token so the map continues to work without interruption.

What's next?

Learn how to use additional location services in these tutorials:

Map of the United States with a dropdown menu for selecting basemap style.

Change the basemap style

Switch a vector basemap style on a map.

Map of Europe with country and city names rendered in Japanese script.

Change language labels

Switch the language of place labels on a basemap.

Search for an address

Find an address or place using a search box.