Display a map (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 that lasts for 12 hours with the MapLibre ArcGIS plugin.

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>MapLibre GL JS 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 credential with the correct privileges to access the resources used in this tutorial.

Go to the Create an API key tutorial to generate an access token that has the following privilege(s):
- Privileges:
  - Location services > Basemaps
Copy the access token to your clipboard when prompted.

Add a <script> element with type="module" 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 type="module">
    const accessToken = "YOUR_ACCESS_TOKEN";

  </script>
Expand

Add script references

Reference the MapLibre GL JS library and the MapLibre ArcGIS plugin.

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

Use dark colors for code blocks
  <meta charset="utf-8" />
  <meta name="viewport" content="initial-scale=1, maximum-scale=1, user-scalable=no" />
  <title>MapLibre GL JS 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;
    }

    .maplibregl-ctrl-bottom-right {
      margin-left: 50px;
    }

  </style>

  <!-- Load MapLibre GL JS from CDN -->
  <script src=https://unpkg.com/maplibre-gl@5.9.0/dist/maplibre-gl.js></script>
  <link href=https://unpkg.com/maplibre-gl@5.9.0/dist/maplibre-gl.css rel="stylesheet" />
  <!-- Load MapLibre ArcGIS from CDN -->
  <script src="https://unpkg.com/@esri/maplibre-arcgis@1.0.0/dist/umd/maplibre-arcgis.min.js"></script>

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.

Start a BasemapSession by calling start() with the required parameters.

Expand
Use dark colors for code blocks
    const basemapSession = await maplibreArcGIS.BasemapSession.start({
      styleFamily: 'arcgis', // basemap style family for the session, e.g. 'arcgis' or 'open'
      token: accessToken,
      duration: 43200, // 12 hours in seconds
      autoRefresh: false
    });
Expand

Create a map

Use the basemap session to load a basemap style. From this point on, all tile requests, including user panning and zooming, will be charged to the basemap session.

Create a Map that is centered on the world.

Expand
Use dark colors for code blocks
    const map = new maplibregl.Map({
      container: "map", // the id of the div element
      zoom: 2, // starting zoom
      center: [-10, 35] // starting location
    });
Expand

Use the plugin to apply a BasemapStyle to the map. Pass the basemap session to the basemap style.

Expand
Use dark colors for code blocks
    const basemapStyle = maplibreArcGIS.BasemapStyle.applyStyle(map, {
      style: 'arcgis/outdoor',
      session: basemapSession
    });
Expand

Handle session expiration

When a basemap session token expires, you need to refresh it so the basemap continues to display without interruption.

Add a BasemapSessionExpired event listener and call refresh() to get a new session and update the basemap with the new session.

Expand
Use dark colors for code blocks
    basemapSession.on("BasemapSessionExpired", () => {
      basemapSession.refresh();
    });
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 basemap with the session 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.