Display a map (basemap session) | ArcGIS Maps SDK for JavaScript

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 individual tile usage, you are only charged once per session.

In this tutorial, you will learn how to 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

Go to CodePen to create a new CodePen app for your mapping application.

The <!doctype html></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 both the opening and closing tag.

Add basic HTML

Define a basic HTML page.

In CodePen > HTML, add HTML to create a basic page.

<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
    <title>ArcGIS Maps SDK for JavaScript Tutorials: Display a map with a basemap session</title>
    <style>
      html,
      body {
        height: 100%;
        margin: 0;
      }
    </style>

  </head>
  <body>

  </body>
</html>

Get an access token

You need an access token with the correct privileges to access the location services 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

In CodePen, set the apiKey property on the global esriConfig variable to your access token.

<!-- The esriConfig variable must be defined before adding the other esri libraries -->
<script>

  var esriConfig = {
    apiKey: "YOUR_ACCESS_TOKEN",
  };

</script>

To learn about other ways to get an access token, go to Types of authentication.

Add references

In the <head>, add the <script> tag for the JavaScript Maps SDK, which includes the Map Components and the Calcite Design System.

19 collapsed lines
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
    <title>ArcGIS Maps SDK for JavaScript Tutorials: Display a map with a basemap session</title>
    <style>
      html,
      body {
        height: 100%;
        margin: 0;
      }
    </style>

    <script>
      var esriConfig = {
        apiKey: "YOUR_ACCESS_TOKEN",
      };
    </script>

    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
    <script type="module" src="https://js.arcgis.com/5.0/"></script>
20 collapsed lines

  </head>
  <body>

    <script type="module">
      const config = await $arcgis.import(["@arcgis/core/config.js"]);

      config.sessions = {
        basemap: {
          enabled: true,
          styleFamily: "arcgis", // basemap style family for the session, e.g. "arcgis" or "open"
          autoRefresh: true, // automatically get new token at end of duration
          duration: 43200, // 12 hours
        },
      };

    </script>

  </body>
</html>

Create a basemap 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.

In a <script> tag, import the config module.

25 collapsed lines
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
    <title>ArcGIS Maps SDK for JavaScript Tutorials: Display a map with a basemap session</title>
    <style>
      html,
      body {
        height: 100%;
        margin: 0;
      }
    </style>

    <script>
      var esriConfig = {
        apiKey: "YOUR_ACCESS_TOKEN",
      };
    </script>

    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
    <script type="module" src="https://js.arcgis.com/5.0/"></script>

  </head>
  <body>

    <script type="module">
      const config = await $arcgis.import(["@arcgis/core/config.js"]);

    </script>
3 collapsed lines

  </body>
</html>

Define a basemap session, setting the styleFamily, duration, and autoRefresh properties.

25 collapsed lines
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
    <title>ArcGIS Maps SDK for JavaScript Tutorials: Display a map with a basemap session</title>
    <style>
      html,
      body {
        height: 100%;
        margin: 0;
      }
    </style>

    <script>
      var esriConfig = {
        apiKey: "YOUR_ACCESS_TOKEN",
      };
    </script>

    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
    <script type="module" src="https://js.arcgis.com/5.0/"></script>

  </head>
  <body>

    <script type="module">
      const config = await $arcgis.import(["@arcgis/core/config.js"]);

      config.sessions = {
        basemap: {
          enabled: true,
          styleFamily: "arcgis", // basemap style family for the session, e.g. "arcgis" or "open"
          autoRefresh: true, // automatically get new token at end of duration
          duration: 43200, // 12 hours
        },
      };

    </script>
3 collapsed lines

  </body>
</html>

Create a map

Use the Map component to set the basemap layer, location and zoom level . The basemap session will be automatically used to load the basemap style.

In the <body> tag, add the <arcgis-map> component and specify the basemap, center and zoom attributes.

<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
    <title>ArcGIS Maps SDK for JavaScript Tutorials: Display a map with a basemap session</title>
    <style>
      html,
      body {
        height: 100%;
        margin: 0;
      }
    </style>

    <script>
      var esriConfig = {
        apiKey: "YOUR_ACCESS_TOKEN",
      };
    </script>

    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
    <script type="module" src="https://js.arcgis.com/5.0/"></script>

  </head>
  <body>

    <arcgis-map basemap="arcgis/outdoor" center="-10, 35" zoom="2">

    </arcgis-map>

    <script type="module">
      const config = await $arcgis.import(["@arcgis/core/config.js"]);

      config.sessions = {
        basemap: {
          enabled: true,
          styleFamily: "arcgis", // basemap style family for the session, e.g. "arcgis" or "open"
          autoRefresh: true, // automatically get new token at end of duration
          duration: 43200, // 12 hours
        },
      };

    </script>

  </body>
</html>

In the <arcgis-map> component, add an <arcgis-zoom> component, which enables users to zoom in and out without a mouse wheel.

25 collapsed lines
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
    <title>ArcGIS Maps SDK for JavaScript Tutorials: Display a map with a basemap session</title>
    <style>
      html,
      body {
        height: 100%;
        margin: 0;
      }
    </style>

    <script>
      var esriConfig = {
        apiKey: "YOUR_ACCESS_TOKEN",
      };
    </script>

    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
    <script type="module" src="https://js.arcgis.com/5.0/"></script>

  </head>
  <body>

    <arcgis-map basemap="arcgis/outdoor" center="-10, 35" zoom="2">

      <arcgis-zoom slot="top-left"></arcgis-zoom>

    </arcgis-map>
17 collapsed lines

    <script type="module">
      const config = await $arcgis.import(["@arcgis/core/config.js"]);

      config.sessions = {
        basemap: {
          enabled: true,
          styleFamily: "arcgis", // basemap style family for the session, e.g. "arcgis" or "open"
          autoRefresh: true, // automatically get new token at end of duration
          duration: 43200, // 12 hours
        },
      };

    </script>

  </body>
</html>

Run the app

In CodePen, run your code to display the map.

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 when needed, starting a new basemap session, and updates the basemap with the session so the map continues to work without interruption.

What’s next?

Learn how to use additional SDK features and ArcGIS services in these tutorials: