Basemap layers
What is a basemap layer?
A basemap layer is a layer that provides the overall visual context for a map or scene. It typically contains geographic features such as continents, lakes, administrative boundaries, streets, cities, and place names. These features are represented with different styles provided by the basemap styles service such as streets, topographic, and imagery. The style you choose depends on the type of application and the visualization you would like to create.
You can use a basemap layer to:
- Display different types of geographic data of the world for both maps and scenes.
- Display default vector tile basemap styles such as streets navigation, light gray canvas, and osm.
- Display custom basemap styles with your own colors, glyphs, and fonts.
- Display default image tile basemap layers for satellite imagery and hillshade.
How a basemap layer works
A basemap layer provides the visual foundation for a mapping application. It typically contains data with global coverage and is the first layer added to a map or scene. The main data source for a basemap layer is the basemap styles service. When a view displays a map, a basemap layer is the first layer to draw, followed by data layers, and then graphics.
Figure 1: A basemap layer provides visual context for a map or scene.
Types of basemap styles
The basemap styles service provides a number of vector tile and image tile basemap styles that you can use to build different types of mapping applications. For example, you can use the Navigation style to create an application that supports driving directions, or you can use Imagery to create an application that displays a real-world view of the earth.
Currently, there are two versions of the basemap styles service available: the basemap styles service (v1) and the basemap styles service v2 (beta).
Vector tile basemaps
Vector tile basemaps are pre-styled vector tile layers provided by a basemap styles service. Vector tile layers are high-performance and well suited for displaying high density geographic data as vector tile data. Vector tile layers are based on the Mapbox specification.
Service URL
To access the default vector tile basemaps styles, most APIs provide enumerations. If they are not available, you can access them directly with the service URL.
Enumerations include:
ArcGIS:
Streets ArcGIS:
Navigation OSM:
Streets
To access vector basemap styles, you specify the type
of JSON to be returned, webmaps
or styles
, the provider arcgis
or osm
, and the basemap style.
Styles inlcude:
arcgis/streets
arcgis/navigation
arcgis/outdoor
Image tile basemaps
Image tile layers are pre-rendered images hosted in ArcGIS and are served as images from https:
. The images are stored on the server at different scales and resolutions. Client applications request images for the appropriate scale and zoom level for the map. Styles include:
- ArcGIS Imagery
- ArcGIS Imagery Standard
- ArcGIS Imagery Labels
- ArcGIS Oceans
- ArcGIS Hillshade Light
- ArcGIS Hillshade Dark
Image tile service URLs are the same for both version one and version two of the service.
To learn more, go to Basemap styles service (v1) or Basemap styles service v2 (beta).
Image tile service URL
You can access image tiles directly by referencing the service URL and specifying the service
.
Template URL examples:
Multi-layer basemap layers
A basemap layer can be composed of one or more layers. Many default styles combine multiple layers. For example:
ArcGIS Streets Relief
combines a layer of streets (ArcGIS Streets Relief Base
) with a backing hillshade layer (ArcGIS Hillshade Light
) to provide topographic context.ArcGIS Imagery
combines a layer of satellite imagery (ArcGIS Imagery Standard
) with a reference layer (ArcGIS Imagery Labels
) of labels and boundaries.
See Basemap styles service (v1) or Basemap styles service v2 (beta).
You can create your own multi-layer basemap by combining layers and specifying which should be treated as reference layers. See the Display a multi-layer basemap layer example.
Code examples
Basemap styles service (v1)
Display a basemap style
This example shows how to use different enumerations to display styles from the basemap styles service (v1).
Steps
- Create a map or scene.
- Reference a basemap layer from the basemap styles service.
- Add the basemap to the map or scene.
- Use an interface to allow users to change the basemap layer.
Topographic
Imagery
Navigation
Light gray canvas
Display a multi-layer basemap layer (v1)
This example shows how to use multiple layers together as a single basemap layer. You can use item IDs for each layer in a multi-layer basemap layer.
Steps
- Reference two or more layers using their item IDs.
- Create a basemap that uses these layers as base layers or reference layers.
- Create a map using the basemap.
Basemap styles service v2 (beta)
Display a basemap style
The basemap styles service (v2) provides additional ArcGIS and OSM basemap styles, including outdoor, OSM navigation, and OSM blueprint. To learn more, go to Basemap styles service (v2).
Steps
- Create a map.
- Reference a basemap layer from the basemap styles service v2 (beta).
- Add the basemap to the map.
Outdoor
OSM Navigation
OSM Blueprint
Localize place labels
An ArcGIS basemap style renders place labels using the default global language setting, typically in English. The OSM map styles, however, render localized place labels. The basemap styles service (v2) provides additional language support so that you can customize the place lable language.
Steps
- Create a map or scene.
- Reference a basemap layer from the basemap styles service v2 (beta).
- In the style URL, set the
language
parameter with a language code. - Add the basemap to the map.
Localized place labels (local)
This example uses the ArcGIS Light Gray map style. By default, place labels display global place names. To render localized place labels, set the language
parameter to local
. The localized labels will render after zoom level 10.
Language-based place labels (global)
This example uses the ArcGIS Dark Gray map style. It sets the language
parameter with a language code, in this case ja
, so that all place labels at varying zoom levels are rendered in Japanese.
Tutorials

Display a map
Create and display a map with the basemap styles service.

Display a scene
Display a scene with the basemap styles service.

Add a point, line, and polygon
Display point, line, and polygon graphics in a map.

Add a feature layer
Access and display point, line, and polygon features from a feature service

Display a web map
Create and display a map from a web map.

Display a web scene
Create and display a scene from a web scene.

Change the basemap layer
Switch a basemap layer from streets to satellite imagery.

Change the place label language
Switch the language of place labels on a basemap.
Services
Basemap styles service v2 (beta)
Access additional basemap styles and customize language settings for place labels.
Basemap styles service (v1)
Access streets, satellite, and other basemap styles for maps and scenes.
API support
2D Display | 3D Display | Basemap layers | Data layers | Graphics | Web maps | Web scenes | |
---|---|---|---|---|---|---|---|
ArcGIS Maps SDK for JavaScript | |||||||
ArcGIS Maps SDK for .NET | |||||||
ArcGIS Maps SDK for Kotlin | |||||||
ArcGIS Maps SDK for Swift | |||||||
ArcGIS Maps SDK for Java | |||||||
ArcGIS Maps SDK for Qt | |||||||
ArcGIS API for Python | |||||||
ArcGIS REST JS | 1 | 1 | 1 | 1 | |||
Esri Leaflet | 2 | 3 | |||||
MapLibre GL JS | 2 | 3 | |||||
OpenLayers | 2 | 3 |
- 1. Access via HTTP request and authentication.
- 2. Access via Feature layer or Image tile layer.
- 3. Access via layers.