Introduction to the Basemap Styles service

What is the Basemap Styles service?

The ArcGIS Basemap Styles service, also referred to as the Basemap Styles service, is a data source that provides basemap styles and data for the world. The style format is a Mapbox style or ArcGIS web map and the data is served as vector tiles and/or map tiles depending on the style used. The data is in the Web Mercator spatial reference. The service provides styles from the ArcGIS Basemap style family and Open Basemap style family. The styles are grouped into the following categories: streets, topography, satellite, reference, and creative. They include a number of popular basemap styles such as streets, navigation, outdoor, and imagery. The service can also display key styles with a preferred language, worldview, or with places.

You can use the service to:

• Build mapping applications to display basemap styles for the world.
• Provide the underlying visual and geographic context for a map.
• Display styles such as streets, navigation, light-gray, and imagery.
• Display families of styles that use authoritative or open source data providers.
• Access styles from ArcGIS Maps SDKs and open source libraries.
• Display your own custom styles created with the ArcGIS Vector Tile Style Editor.
• Display styles with a preferred language, worldview, or with places.

How to use the Basemap Styles service

To request a basemap style, you need to use a mapping API that supports either a Mapbox style or ArcGIS web map format. You can get a style by using the service URL with the appropriate path parameters and query parameters. The path parameters specify the style response, style family, and style name. When using the ArcGIS Maps SDKs, helper classes and enumerations can be used to access each style. When using open source libraries, you typically need to define the service URL and path parameters yourself. You may also need to manually provide Esri and data attribution. The query parameters can be used to set preferences for the style returned.

The steps to use the service are:

1. Get an access token with the correct privilege.
2. Define the service URL and path parameters for the appropriate style response, style family, and style name.
3. Set the query parameters to display the preferred language, worldview, and places.

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
      const navigation = new Basemap({
          style: new BasemapStyle({
            id: "arcgis/navigation" //arcgis/navigation, //arcgis/topographic
          })
        });

      const map = new Map({
        basemap: navigation,
        constraints: {
          snapToZoom: false,
        },
      });

Service URL

1
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2

Path parameters

These are required parameters to specify the style to access.

1
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/{style_response}/{style_family}/{style_name}

Query parameters

These are optional parameters to set style preferences and the access token. Some are only available for key styles.

Tokens

To request styles from the basemap service, you need an access token or a session token.

Access token

To use an access token, you first need to implement a type of authentication. The resulting token must have the premium:user:basemaps privilege. Using the access token directly to access styles will result in basemap tile usage charges. To learn more, go to Basemap usage > Tile usage model.

Session token

To use a session token, you first have to start a basemap session to get the token. This will result in basemap session usage charges To learn how learn more, go to Basemap usage > Session usage model.

How to use tokens

To include a token with requests to basemap styles, you can use a query parameter or authorization header.

Query parameter

An access token or session token can be used as the value of the token query parameter.

1
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/{style_response}/{style_family}/{style_name}?token=<YOUR_TOKEN>

Authorization header

Only an access token can be used as the value for an authorization header.

1
2
3
GET https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/{style_response}/{style_family}/{style_name} HTTP/1.1
  Host: basemapstyles-api.arcgis.com
  Authorization: Bearer <YOUR_TOKEN>

Attribution

All applications that use an ArcGIS API, SDK, service, content, or data must display Esri and data attribution. This also applies to applications that use ArcGIS Basemap services. When using the ArcGIS Maps SDKs, the correct attribution is typically displayed for you in the map. However, when using open source or other third party libraries, you may need to take additional steps to access the basemap service and display the attribution for Esri and data providers.

Style response

The style response is the type of JSON structure returned for a basemap style.

1
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/{style_family}/{style_name}

1
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/webmaps/{style_family}/{style_name}

Style families

A style family is the name for a set of styles that use the same set of data providers.

1
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/self

1
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/webmaps/self

1
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/self

1
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/webmaps/self

Style names

The style name is the name of a style in a style family.

1
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/arcgis/{style_name}

1
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/webmaps/arcgis/{style_name}

1
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/{style_response}/{style_family}/{style_name}/self

1
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/arcgis/navigation

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
{
  "glyphs": "https://basemaps-api.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer/resources/fonts/{fontstack}/{range}.pbf?token={{ACCESS_TOKEN}}",
  "layers": [
      {
          "id": "Land",
          "type": "fill",
          "source": "esri",
          "filter": [
              "in",
              "_symbol",

1
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/open/{style_name}

1
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/webmaps/open/{style_name}

1
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/{style_response}/{style_family}/{style_name}/self

1
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/open/streets

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
{
  "glyphs": "https://basemapsdev-api.arcgis.com/arcgis/rest/services/OpenBasemap_v2/VectorTileServer/resources/fonts/{fontstack}/{range}.pbf?token=AAPTKUgfudpnh_cXrZ7wRiqGE3kjukpnhD8EUuZ103CLhHyQ5e-XnZBYEcG6OTaRAh5cfjY9VLXIAMBRR1Js87_rWtNBdNvrXZw7QOOmveYRQ8Dn0XmTvXRYQV85sdrX6mSGNneqP-5KkPDAdwpIdNToiUoKBaCYgHlwApFlbaD84uuWcAbGy4vU-QpRnxdXu0FpezMHkfG5M9uC15_3SEfq8DarBLrGQnP-dntOFFFBc9g.AT1_Xm8uziUg",
  "layers": [
    {
      "id": "land base",
      "type": "fill",
      "source": "esri-open",
      "paint": {
        "fill-color": "#f7f6d5"
      },

What's next?

Learn how to build mapping applications with the basemap style service.