Display a map with a basemap session

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

The ArcGIS Basemap Styles service 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 every tile request, you are only charged once per session.

In this tutorial, display a map using a basemap session.

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 the HTML to create a page with a map. Add the map div to display a map using CSS to make it full width and height.

The <!DOCTYPE html> tag is not required in CodePen. If you are using a different editor or running the page on a local server, be sure to add this tag to the top of your HTML page.

Use dark colors for code blocks
<!DOCTYPE html>
<html>


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

  <style>
    body {
      margin: 0;
      padding: 0;
    }

    #map {
      position: absolute;
      top: 0;
      bottom: 0;
      right: 0;
      left: 0;
      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 credential with the correct privileges to access the resources used in this tutorial.

Go to the Create an API key tutorial and create an API key with the following privilege(s):
- 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 token. Set YOUR_ACCESS_TOKEN with the access token you previously copied from your API key credentials.

Expand
Use dark colors for code blocks
  <script>

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

    const map = L.map("map", {
      minZoom: 2
    })

    map.setView([30, -20], 3);

    const basemapEnum = "arcgis/outdoor";

    L.esri.Vector.vectorBasemapLayer(basemapEnum, {
      token: accessToken
    }).addTo(map);

  </script>
Expand

Add script references

To access vector basemap layers, you need to reference the leaflet libraries as well as the esri-leaflet and esri-leaflet-vector plugins. 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 Leaflet from CDN -->
  <link rel="stylesheet" href="https://unpkg.com/leaflet@1.9.4/dist/leaflet.css" crossorigin="" />
  <script src="https://unpkg.com/leaflet@1.9.4/dist/leaflet.js" crossorigin=""></script>
  <!-- Load Esri Leaflet from CDN -->
  <script src="https://unpkg.com/esri-leaflet@3.0.19/dist/esri-leaflet.js"></script>
  <script src="https://unpkg.com/esri-leaflet-vector@4.3.1/dist/esri-leaflet-vector.js"></script>
  <!-- ArcGIS REST JS: request and basemap sessions -->
  <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 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 getBasemapSession 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
    let basemapSession;

    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. From this point onward, all tile requests, including user panning and zooming, will be charged to the basemap session.

Declare the map and basemapLayer variables globally so they 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, basemapLayer;

Expand

Create a function called loadMap that initializes a map and adds a basemap style with a session token to the map.

Expand
Use dark colors for code blocks
    async function loadMap(sessionToken) {
      map = L.map("map").setView([30, -20], 3);

      basemapLayer = L.esri.Vector.vectorBasemapLayer(basemapStyle, {
        token: sessionToken,
      }).addTo(map);
    }
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
    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 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 the basemap. You will create the applyToken function in the next step.

Expand
Use dark colors for code blocks
    async function initApp() {
      basemapSession = await createBasemapSession();

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

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

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

    initApp()
Expand

Create a function called applyToken that removes the existing basemap layer and re-adds it with a new session token.

Expand
Use dark colors for code blocks
    function applyToken(newToken) {
      if (basemapLayer) {
        map.removeLayer(basemapLayer);
      }

      basemapLayer = L.esri.Vector.vectorBasemapLayer(basemapStyle, {
        token: newToken,
      }).addTo(map);
    }
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 reapplies the basemap 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:

Change the basemap style

Switch a vector basemap style on a map.

Change language labels for basemap styles

Switch the language of place labels on a basemap.

Search for an address

Find an address or place using a search box.