Basemap layer service

The basemap layer service provides global basemap layers in a variety of styles to use in mapping applications. Basemap layers give geographic context to a map or scene by serving static tiles containing geographic reference data. This data includes, but is not limited to, topographic features, road networks, footpaths, building footprints, water features, administrative boundaries, and labels.

ArcGIS:Community basemap style from the basemap layer service

Key features

Some key features of the basemap layer service are:

  • Basemap layers are highly optimized for fast, efficient rendering.
  • Depending upon the basemap layer, data is served as vector tiles or image tiles:
    • Vector tiles contain vector data that is rendered on the client.
    • Image tiles are pre-rendered image files (typically PNGs or JPGs).
  • Basemap layers include many different styles, including:
    • Day and night navigation styles, useful for driving.
    • Light and dark street focused styles, useful for urban areas.
    • Topographic and terrain styles, useful for rural areas.
    • Imagery from satellite and aerial sources that shows real-world geography.
    • Light and dark gray canvas for accentuating overlaid data.
  • You can also create your own custom basemap layer styles using the ArcGIS Vector Tile Style Editor.
  • Many basemap layers have options to show localized labels.
  • Vector tile basemap layers can be configured to accommodate boundary disputes.
  • Basemap layers can be used offline in applications built with ArcGIS Runtime APIs.

The basemap style you use depends on the purpose of your application, your users' needs, and on the nature of your application's data.

How the basemap layer service works

To access a basemap layer, you access the basemap style URLs to get a JSON definition for a particular basemap style. This definition includes references to one or more tile service URLs.

The basemap layer service includes two sets of URLs:

  • Basemap style URLs provide a JSON style definition for a basemap style.
  • Tile service URLs provide vector tiles or image tiles used by a basemap style.

Basemap styles

The basemap style URL provides an easy way to access the basemap style definitions. You request a basemap style by providing the basemapStyle and type parameters. The response is a JSON structure that defines the basemap style, including references to the individual tile layers used by the style. The format of the JSON structure depends on the type parameter.

Service URL

 
1
https://basemaps-api.arcgis.com/arcgis/rest/services/styles/{basemapStyle}?type={type}&token=<ACCESS_TOKEN>

Parameters

token

The access token used to access the service. The value can be an API Key or OAuth 2.0 token.

Learn more about access tokens and authentication methods in Security and authentication.

basemapStyle

The basemapStyle is specified as part of the URL. It can reference the default basemap styles, or a custom basemap style created with the ArcGIS Vector Tile Style Editor.

Default basemap styles

Here are the available default basemap styles:

Streets & NavigationImagery & TopographyOpenStreetMapCreative
ArcGIS:DarkGrayArcGIS:Navigation
ArcGIS:DarkGray:BaseArcGIS:NavigationNight
ArcGIS:DarkGray:LabelsArcGIS:Streets
ArcGIS:LightGrayArcGIS:StreetsNight
ArcGIS:LightGray:BaseArcGIS:StreetsRelief
ArcGIS:LightGray:LabelsArcGIS:StreetsRelief:Base
ArcGIS:ImageryArcGIS:Topographic
ArcGIS:Imagery:StandardArcGIS:Topographic:Base
ArcGIS:Imagery:LabelsArcGIS:Terrain
ArcGIS:OceansArcGIS:Terrain:Base
ArcGIS:Oceans:BaseArcGIS:Terrain:Detail
ArcGIS:Oceans:LabelsArcGIS:Hillshade:Dark
ArcGIS:Hillshade:Light
OSM:DarkGrayOSM:Standard
OSM:DarkGray:BaseOSM:StandardRelief
OSM:DarkGray:LabelsOSM:StandardRelief:Base
OSM:LightGrayOSM:Streets
OSM:LightGray:BaseOSM:StreetsRelief
OSM:LightGray:LabelsOSM:StreetsRelief:Base
ArcGIS:ColoredPencilArcGIS:Community
ArcGIS:NovaArcGIS:ChartedTerritory
ArcGIS:MidcenturyArcGIS:ChartedTerritory:Base
ArcGIS:Newspaper
ArcGIS:ModernAntique
ArcGIS:ModernAntique:Base

basemapStyle is constructed of two or three parts:

  • {Provider}:{Style name} or
  • {Provider}:{Style name}:{Component}

where the parts are:

  • Provider is the source of the basemap layer content: either ArcGIS or OSM.
  • Style name defines the look of the basemap layer.
  • Component optionally specifies a particular component of a multi-layer basemap. This is typically Base or Labels.
Providers

Many basemaps contain content from the ArcGIS Community Basemap, such as:

  • ArcGIS:DarkGray
    • The data content provider is ArcGIS.
    • The style of the basemap is DarkGray.

Some styles can contain OpenStreetMap content instead. For example:

  • OSM:DarkGray
    • The data content provider is OSM (OpenStreetMap).
    • The style of the basemap is DarkGray.

Learn more about basemap layer data content providers.

Components

Some basemap styles include multiple layers. For example, DarkGray includes a base layer and a labels layer:

  • ArcGIS:DarkGray:Base
    • The data content provider is ArcGIS.
    • The style of the basemap is DarkGray.
    • The component of the DarkGray basemap is the Base layer. This provides the geographic content of the basemap, displayed behind data layers.
  • ArcGIS:DarkGray:Labels
    • The data content provider is ArcGIS.
    • The style of the basemap is DarkGray.
    • The component of the DarkGray basemap is the Labels layer. This provides labels and boundaries that are overlaid on top of data layers.

If a component is not specified for a multi-layer basemap style, then the returned JSON will include references to all components of the style.

  • ArcGIS:DarkGray
    • The data content provider is ArcGIS.
    • The style of the basemap is DarkGray.
    • There is no component specifier; this is the entire DarkGray ArcGIS basemap, including Base and Labels layers.

Not all basemap styles are multi-layer basemap layers. For example: ArcGIS:Navigation, ArcGIS:Topographic, and OSM:Streets.

Custom basemap styles

basemapStyle is the item ID of a custom basemap style created with the ArcGIS Vector Tile Style Editor, for example d2ff12395aeb45998c1b154e25d680e5.

type

The type parameter specifies whether to return the basemap JSON as an Esri web map, or as a Mapbox style definition.

TypeDescription
styleMapbox style JSON: This is defined by the Mapbox Style Specification. This format is typically used by open source and third party APIs. The JSON response is a JSON style definition with references to individuals layers.
webmapEsri web map JSON: This is defined by the Esri Web Map Specification. This format is typically used by ArcGIS APIs. The JSON response is ArcGIS web map JSON containing a baseMap object with references to individual layers).

Examples

Get a basemap style with type style

Get the ArcGIS:DarkGray basemap style definition with the type=style. This is typically used by non-ArcGIS APIs.

RequestResponse
 
1
https://basemaps-api.arcgis.com/arcgis/rest/services/styles/ArcGIS:DarkGray/?type=style&token=<ACCESS_TOKEN>
                                                                                                                         
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
{
  "version": 8,
  "sprite": "https://cdn.arcgis.com/sharing/rest/content/items/5e9b3685f4c24d8781073dd928ebda50/resources/styles/../sprites/sprite?token=AAPKc56d587fc6774b2fb4d866c50b227bdeHgve6W4_2bXsjC6IkMHLmB0P5uyhjnrPmA42Ce3qm2IQbqWz2aLlaFFUAvwcxpjt",
  "glyphs": "https://basemaps-api.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer/resources/fonts/{fontstack}/{range}.pbf?token=AAPKc56d587fc6774b2fb4d866c50b227bdeHgve6W4_2bXsjC6IkMHLmB0P5uyhjnrPmA42Ce3qm2IQbqWz2aLlaFFUAvwcxpjt",
  "sources": {
    "esri": {
      "type": "vector",
      "url": "https://basemaps-api.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer?token=AAPKc56d587fc6774b2fb4d866c50b227bdeHgve6W4_2bXsjC6IkMHLmB0P5uyhjnrPmA42Ce3qm2IQbqWz2aLlaFFUAvwcxpjt",
      "minzoom": 0,
      "maxzoom": 16,
      "tiles": [
        "https://basemaps-api.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer/tile/{z}/{y}/{x}.pbf?token=AAPKc56d587fc6774b2fb4d866c50b227bdeHgve6W4_2bXsjC6IkMHLmB0P5uyhjnrPmA42Ce3qm2IQbqWz2aLlaFFUAvwcxpjt"
      ],
      "copyrightText": "Sources: Esri, HERE, Garmin, FAO, NOAA, USGS, © OpenStreetMap contributors, and the GIS User Community",
      "attribution": "Sources: Esri, HERE, Garmin, FAO, NOAA, USGS, © OpenStreetMap contributors, and the GIS User Community"
    }
  },
  "layers": [
    {
      "id": "background",
      "type": "background",
      "paint": {
        "background-color": "#1d2224"
      }
    },
    {
      "id": "Land",
      "type": "fill",
      "source": "esri",
      "source-layer": "Land",
      "minzoom": 0,
      "layout": {},
      "paint": {
        "fill-color": {
          "stops": [
            [
              0,
              "#3b3c3c"
            ],
            [
              12,
              "#353636"
            ],
            [
              15,
              "#323333"
            ]
          ]
        }
      }
    },
    {
      "id": "Urban area",
      "type": "fill",
      "source": "esri",
      "source-layer": "Urban area",
      "minzoom": 5,
      "maxzoom": 15,
      "layout": {},
      "paint": {
        "fill-color": {
          "stops": [
            [
              5,
              "#2F3030"
            ],
            [
              10,
              "#323333"
            ]
          ]
        }
      }
    },
    {
      "id": "Openspace or forest",
      "type": "fill",
      "source": "esri",
      "source-layer": "Openspace or forest",
      "minzoom": 12,
      "layout": {},
      "paint": {
        "fill-color": {
          "stops": [
            [
              7,
              "#373837"
            ],
            [
              9,
              "#373938"
            ]
          ]
        },
        "fill-outline-color": "#373938"
      }
    },
    {
      "id": "Admin0 forest or park",
      "type": "fill",
      "source": "esri",
      "source-layer": "Admin0 forest or park",
      "minzoom": 7,
      "layout": {},
      "paint": {
        "fill-color": {
          "stops": [
            [
              7,
              "#373837"
            ],
            [
              9,
              "#373938"
            ]
          ]
        },
        "fill-outline-color": "#373938"
      }
    },
    ...

Get a basemap style with type webmap

Get the ArcGIS:DarkGray basemap style definition with type=webmap. Typically used by ArcGIS APIs.

RequestResponse
 
1
https://basemaps-api.arcgis.com/arcgis/rest/services/styles/ArcGIS:DarkGray/?type=webmap&token=<ACCESS_TOKEN>
                                   
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
{
  "authoringApp": "ArcGIS Basemap Style API",
  "authoringAppVersion": "1.0",
  "version": "2.17",
  "operationalLayers": [],
  "baseMap": {
    "title": "ArcGIS:DarkGray",
    "baseMapLayers": [
      {
        "id": "5e9b3685f4c24d8781073dd928ebda50",
        "title": "World_Basemap_v2",
        "type": "VectorTileLayer",
        "layerType": "VectorTileLayer",
        "isReference": false,
        "styleUrl": "https://basemaps-api.arcgis.com/arcgis/rest/services/styles/ArcGIS:DarkGray:Base",
        "opacity": 1,
        "visibility": true
      },
      {
        "id": "747cb7a5329c478cbe6981076cc879c5",
        "title": "World_Basemap_v2",
        "type": "VectorTileLayer",
        "layerType": "VectorTileLayer",
        "isReference": true,
        "styleUrl": "https://basemaps-api.arcgis.com/arcgis/rest/services/styles/ArcGIS:DarkGray:Labels",
        "opacity": 1,
        "visibility": true
      }
    ]
  },
  "spatialReference": {
    "wkid": 102100,
    "latestWkid": 3857
  }
}

Tile services

You can access tile services directly with a URL. A basemap style definition JSON includes templates URLs to get individual basemap tiles which are displayed together to form a seamless map. Tiles are downloaded by providing x, y, and z (zoom level) values to the tile service.

A basemap style can use vector tiles and/or image tiles

Each component of a basemap (such as Base or Labels) will use a single type of tile

.

Vector tile URL

Vector tiles are served as PBF (Protocolbuffer Binary Format) tiles from https://basemaps-api.arcgis.com.

Vector tiles contain static vector data which is rendered on the client using the basemap style definition.

Template URL for ArcGIS provider tiles:

 
1
https://basemaps-api.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer/tile/{z}/{y}/{x}.pbf?token=<ACCESS_TOKEN>

Template URL for OSM provider tiles:

 
1
https://basemaps-api.arcgis.com/arcgis/rest/services/OpenStreetMap_v2/VectorTileServer/tile/{z}/{y}/{x}.pbf?token=<ACCESS_TOKEN>

Image tile URL

Image tiles are pre-rendered and are served as images from https://ibasemaps-api.arcgis.com

Tiles are typically 256x256 pixel, 96 ppi PNG or JPEG images

. The full template URL including the serviceName is returned in the basemap style JSON.

Template URL examples:

 
1
https://ibasemaps-api.arcgis.com/arcgis/rest/services/Ocean/World_Ocean_Base/MapServer/tile/{z}/{y}/{x}?token=<ACCESS_TOKEN>
 
1
https://ibasemaps-api.arcgis.com/arcgis/rest/services/Elevation/World_Hillshade/MapServer/tile/{z}/{y}/{x}?token=<ACCESS_TOKEN>
 
1
https://ibasemaps-api.arcgis.com/arcgis/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}?token=<ACCESS_TOKEN>

To read metadata about an image tile service, including the tiling scheme, visit the service root page:

 
1
https://ibasemaps-api.arcgis.com/arcgis/rest/services/{serviceName}/MapServer?token=<ACCESS_TOKEN>

Custom basemap styles

Use the Vector Tile Style Editor to create custom basemap styles. These custom basemap styles use the same vector tiles as the default ArcGIS provider styles, but using your custom style definition.

API support

Full supportPartial supportNo support
  • 1. 2D only

Authentication

To make authenticated requests you need to use one of the following:

  • API key: A permanent token that grants your application access to ready-to-use services and, with an ArcGIS Developer account, private content (currently in beta).
  • ArcGIS Identity (formerly named user): Grants a short-lived token, generated via OAuth 2.0, giving your application permission to access the content and services authorized to an existing ArcGIS user's account.

Learn more about getting access tokens in Security and authentication.

Service data

Data providers

The data sources contributing to a basemap service layer depend on the layer. For example, imagery data is provided by a number of sources such as Maxar, Earthstar Geographics, CNES/Airbus DS, and GeoEye. Vector tile services derive their data from HERE, Garmin, FAO, NOAA, USGS, OpenStreetMap contributors, and local authorities (provided via the community maps program). The dedicated OpenStreetMap maps are 100% OpenStreetMap data.

Attribution

Basemap attribution is required when you build and deploy an application which uses the Basemap layer service. There are two types of attribution that you need to display in your application:

  • Powered by Esri
  • Attribution for the data source providers.

Most client APIs display attribution text by default. If the API you are using does not provide the appropriate attribution, you need to add it manually. For more information, visit basemap attribution.

Detail and accuracy

The detail and accuracy of the data varies across the globe.

Projections

Basemaps service layers are published in the Web Mercator (Auxiliary Sphere) projection.

Languages

Basemaps service layers have global labeling in English. Vector tile basemap layers are available in other languages.

Boundary disputes

Vector basemap service layers can be configured to display disputed boundaries according to a specific world view. This requires modifying the style definition JSON.

The source Esri Community Map data used to build the vector tiles has disputed boundaries defined for many areas around the world. In the Esri vector basemaps, internationally recognized national boundaries (e.g. United States / Canada border) are typically represented with different types of “solid” lines while disputed boundaries (e.g. parts of French Guiana / Suriname border) are typically represented with “dashed” lines. In some cases, a country will want to not render (i.e. make invisible) a disputed boundary that it does not recognize. See this blog for an example of how to change the JSON code and apply the DisputeID code in the filter for boundary lines.

Visit this web map to view details of all the disputed boundaries, with DisputeID codes, configured in the Esri Vector Basemaps.

Tutorials

APIs
Tools

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.