Basemap usage

What is basemap usage?

As a developer, you can implement a basemap usage model in your application to control the type of basemap usage that occurs. You can use a model that results in usage for the number of basemap tiles consumed or the number of basemap sessions created.

Types of usage models

The two types of usage models you can implement with the ArcGIS Basemap Styles service are the following:

• Tile usage model: Usage for the total number of basemap tiles consumed.
• Session usage model: Usage for the total number of basemap sessions created.

Tile usage model

The tile usage model is an application programming pattern that results in the consumption of basemap tiles. Usage occurs for every request to the service that returns basemap tiles.

This usage model requires an access token to make requests directly to the basemap service for a style. The style request results in tiles returned to the application. Tiles are returned when a map loads and displays a basemap style, when the basemap style is changed, and when user interactions occur such as panning, zooming, or navigating the map.

How to use

To create an application that uses the tile usage model, you simply need an access token with the privilege to access basemaps. In most cases, you use API key authentication to get an access token. The access token can be used to access all styles available in the Basemap Styles service.

1. Get an access token

Go to the Create an API key tutorial to get an access token with the premium:user:basemaps privilege.

1
  const accessToken = <YOUR_ACCESS_TOKEN>

2. Access a basemap style

Use the access token to create a style URL reference to the basemap service.

1
2
3
4
5
6
7
8
9
10
11
12
  function loadMap(accessToken) {
    const style = `https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/arcgis/outdoor?token=${accessToken}`;

    const map = new maplibregl.Map({
      container: 'map',
      style: style,
      zoom: 2,
      center: [-30,20]
    });
  }

  loadMap(accessToken);

Code example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
      const accessToken = "YOUR_ACCESS_TOKEN"

      // Access the basemap service and style
      const map = new maplibregl.Map({
        container: "map",
        style: `https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/open/osm-style-relief?token=${accessToken}`,
        zoom: 13, // starting zoom
        center: [-119.0265, 37.639], // starting location [longitude, latitude]
        maxZoom: 16, // limit zoom out
        minZoom: 12, // limit zoom in
        maxBounds: [ // limit map extent for pan
          [-119.1486, 37.5667],
          [-118.9147, 37.6956],
        ]
      })

      // Limit user interactions
      map.dragRotate.disable()
      map.touchZoomRotate.disableRotation()
      map.setMaxPitch(0)
      map.setMinPitch(0)
      map.touchPitch.disable()

Session usage model

The session usage model is an application programming pattern that results in the creation of basemap sessions. A basemap session is a time frame during which a single user of a single application can use a session token to access unlimited basemap tiles from the Basemap Styles service.

This usage model requires creating and managing a basemap session in your application. When you create a basemap session, you can define the length of time the basemap session (and session token) is valid for. The maximum length of time for a session is 12 hours. When you create a session, you also need to define the basemap style family it applies to, either arcgis or open styles.

After a basemap session is created, you use the session token to access styles from the basemap service. A session token is used in a similar way to how access tokens are used to access basemap styles. However, a session token can only access the basemap service it was created from, and it can only access styles that belong to the basemap style family specified when it was created.

During the lifespan of a basemap session, you use the session token to make all requests to the basemap service for styles and tiles. This includes the initial request to load the map and style, requests to change the style in the map, and for all other requests that result from interactions such as panning, zooming, and map exploration. When the basemap session expires, you can create a new basemap session (and session token) to ensure uninterrupted usage.

Learn how to create and manage a basemap session in How to use.

How to use

To create an application that uses basemap sessions, you need an ArcGIS Location Platform account. You use the account to implement API Key authentication to get an access token. The access token must contain the basemap privilege (premium:user:basemaps) to access the service. You can use the access token to create a basemap session and get a session token. Once obtained, you use the session token to make all subsequent requests to the service for basemap styles and tiles. The session token cannot be used to access other services. When the session token expires, you can generate a new token by starting a new basemap session.

1. Get an access token

Go to the Create an API key tutorial to get an access token with the premium:user:basemaps privilege.

1
  const accessToken = <YOUR_ACCESS_TOKEN>

2. Create a basemap session

Create a basemap session by making a request to the Basemap Styles service /sessions/start endpoint with the access token. Include the styleFamily parameter to define the type of basemap styles it will be able to access.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
  const createBasemapSession = async (accessToken) => {
    const basemapSession = await fetch(`https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/sessions/start?` + new URLSearchParams({
        styleFamily:"arcgis", // Basemap styles the session token can access
        durationSeconds: 43200, // Maximum duration (12hrs)
    }).toString(),{
        method:'GET',
        headers: {
          "Authentication":`Bearer ${accessToken}`
        }
    })
    return await basemapSession.json();
  }

  let basemapSession = await createBasemapSession(accessToken);

3. Access a basemap style

Use the session token to access a basemap style in the styleFamily and display a map.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
  const loadMap = (sessionToken, styleName) => {
    const styleURL = `https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/${styleName}?token=${sessionToken}`;

    if (!map) {
      map = new maplibregl.Map({
        container: 'map',
        style: styleURL,
        zoom: 2,
        center: [-30,20]
      });
    } else {
      map.setStyle(styleURL)
    }
  }

  let basemapSession = await createBasemapSession(accessToken);

  let map = loadMap(basemapSession.sessionToken, "arcgis/navigation");

4. Refresh when expired

Start a new session and update the map when the original session token is expired.

1
2
3
4
5
6
7
8
9
10
  const isExpired = () {
    return Date.now() > Date(basemapSession.endTime);
  }

  if (isExpired()) {
    // Start new session
    basemapSession = await createBasemapSession(accessToken);
    // Update map with new style and token
    map = loadMap(basemapSession.sessionToken, "arcgis/navigation");
  }

Code example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
      const initApp = async () => {

        // Create the basemap session
        basemapSession = await arcgisRest.BasemapStyleSession.start({
          authentication: authentication,
          styleFamily: "arcgis", // Access all styles in this family
          duration: 43200 // 12 hours
        })

        // Session is expired, start a new session
        basemapSession.on("expired", () => {
          // Notify session is expired
          alert("Session Expired. Click OK to continue.")
          // Start a new session
          basemapSession.refreshCredentials().then(() => {
            displayMap(basemapSession.token)
          })
        })

        // Display a basemap style with the session token
        displayMap(basemapSession.token)
      }