Display a map with a basemap session (2 of 4) | MapLibre GL JS

Use the MapLibre ArcGIS plugin to create a basemap session to display the arcgis/community basemap style.

Display a basemap using a basemap session.

Prerequisites

You need an ArcGIS Location Platform account.
You need to complete Step 1. Create an API key.

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>MapLibre ArcGIS</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>

Add script references

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

In the HTML <head>, add the following <link> and <script> references.

Use dark colors for code blocks
    <!-- Load MapLibre GL JS from CDN -->
    <script src="https://unpkg.com/maplibre-gl@5.10.0/dist/maplibre-gl.js"></script>
    <link href="https://unpkg.com/maplibre-gl@5.10.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>

Set the access token

Add a <script> element with type="module" in the HTML. Then, create an accessToken variable to store your access token. Set YOUR_ACCESS_TOKEN with the access token you previously copied.

Expand
Use dark colors for code blocks
    <script type="module">
    const accessToken = "YOUR_ACCESS_TOKEN";

    </script>
Expand

Create a basemap session

Use the MapLibre ArcGIS plugin to start a basemap session that is valid for 12 hours (43200 seconds). This provides unlimited access to basemap tiles for the duration of the session. When the session expires, automatically start a new session to ensure uninterrupted map usage for the user.

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

Expand
Use dark colors for code blocks
    const basemapSession = await maplibreArcGIS.BasemapSession.start({
      token: accessToken,
      styleFamily: "arcgis",
      duration: 43200, // 12 hours in seconds
      autoRefresh: false
    });

Expand

Handle session expiration by adding an event listener. When the session expires, call refresh() to get a new one.

Expand
Use dark colors for code blocks
    const basemapSession = await maplibreArcGIS.BasemapSession.start({
      token: accessToken,
      styleFamily: "arcgis",
      duration: 43200, // 12 hours in seconds
      autoRefresh: false
    });

    basemapSession.on("BasemapSessionExpired", () => {
      basemapSession.refresh();
    });
Expand

Create a map

Create a map to display an ArcGIS basemap style centered on Edinburgh, Scotland. Use the MapLibre ArcGIS plugin to access the basemap style.

Create a Map that centers on Edinburgh, Scotland.

Expand
Use dark colors for code blocks
    const map = new maplibregl.Map({
      container: "map",
      zoom: 11,
      center: [-3.189, 55.953] // Edinburgh
    });

Expand

Use the plugin to apply a new BasemapStyle to the map. The plugin will automatically apply Esri and data attribution.

Expand
Use dark colors for code blocks
    const map = new maplibregl.Map({
      container: "map",
      zoom: 11,
      center: [-3.189, 55.953] // Edinburgh
    });

    const basemapStyle = maplibreArcGIS.BasemapStyle.applyStyle(map, {
      style: "arcgis/community",
      session: basemapSession
    });

Expand

One of the benefits of using a basemap session is that you can freely interact with the map, including panning, zooming, and adjusting the pitch, without incurring extra tile request charges. All map interactions are covered under the single session charge.

Add a navigation control so users can explore the map easily.

Expand
Use dark colors for code blocks
    map.addControl(new maplibregl.NavigationControl({ visualizePitch: true }), "top-right");
Expand

Run the app

Run the app.

The map should display the arcgis/community style from the Basemap Styles service using a basemap session.

Get started

1. Create an API key

2. Create a basemap session

3. Change the basemap style

4. Add search