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 The 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 timeframe during which a single user of a single application can use a session token to access unlimited basemap tiles from the Basemap Styles service. It is created a session starts and valid for a maximum duration of 12 hours. Learn more . 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 An 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 with the correct privileges to access the location services ArcGIS Location Services, also referred to as Location Services, are services hosted by Esri that provide geospatial functionality for developing mapping applications. They include the ArcGIS Basemap Styles service, ArcGIS Static Basemap Tiles service, ArcGIS Places service, ArcGIS Geocoding service, ArcGIS Routing service, ArcGIS GeoEnrichment service, and ArcGIS Elevation service. An ArcGIS Location Platform or ArcGIS Online account is required to use the services. Learn more used in this tutorial.

Go to the Create an API key tutorial and create an API key An 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

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 A basemap layer is the layer in a map or scene that displays basemap data. The data source for a basemap layer is typically a basemap service. Learn more layer, location A location is a position or region (point, line, or polygon) on the earth's surface. Learn more and zoom level Zoom level is a value that sets the scale for a map view or a scene view. Learn more . 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: