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.
Key features
Some key features of the basemap styles 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 Maps SDKs for Native Apps.
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 styles service works
There are two ways to access basemap layers:
- Basemap styles service: Access the basemap styles service with a URL and parameters to get the JSON definition for a specific basemap style. There are over 25 styles available. For example:
https:
- Tile services: Access the vector tile service or image tile service with a formatted URL to access the tiles directly. For example:
https:
Basemap styles service
The basemap style service provides an easy way to access the basemap style definitions. You request a basemap style by providing the basemap 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 JSON structure can be returned as the Mapbox Style Specification or the Esri Web Map Specification.
Basemap styles service URL
https://basemaps-api.arcgis.com/arcgis/rest/services/styles/{basemapStyle}?type={type}&token=<ACCESS_TOKEN>Learn more about standard and enhanced endpoints in Service endpoints.
Required parameters
Name | Description | Examples |
|---|---|---|
basemap | The name of the style. It can reference a default basemap style name or a custom basemap style ID. See all of the style names below. | basemapbasemap |
type | Specifies whether to return the basemap JSON as an Esri web map or as a Mapbox style definition. The value can be style or webmap.style Mapbox 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. webmap Esri 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). | type=styletype=webmap |
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. | token=< |
Default styles
To use a default style, set the basemap parameter to one of the style names below. To view the styles in more detail, click the images or go to the World basemaps for developers group.
Streets and navigation
| Name | Layer sources | View in ArcGIS |
|---|---|---|
| Multiple | | |
Single | | |
Single |  | |
Multiple |  | |
Single |  | |
Single |  | |
Single |  | |
Single |  | |
Single |  | |
Multiple |  | |
Single |  | |
Single |  |
Imagery and topography
| Name | Layer sources | View in ArcGIS |
|---|---|---|
Multiple |  | |
Single |  | |
Single |  | |
Multiple |  | |
Single |  | |
Multiple |  | |
Single |  | |
Single |  | |
Multiple |  | |
Single |  | |
Single |  | |
Single |  | |
Single |  |
OpenStreetMap
| Name | Layer sources | View in ArcGIS |
|---|---|---|
Single |  | |
Multiple |  | |
Single |  | |
Multiple |  | |
Single |  | |
Single |  | |
Multiple |  | |
Single |  | |
Single |  | |
Single |  | |
Multiple |  | |
Single |  |
Creative
| Name | Layer sources | View in ArcGIS |
|---|---|---|
Multiple |  | |
Single |  | |
Single |  | |
Single |  | |
Multiple |  | |
Single |  | |
Single |  | |
Single |  | |
Single |  | |
Single |  | |
Single |  | |
Multiple |  | |
Single |  | |
Single |  | |
Single |  | |
Multiple |  | |
Single |  |
Custom styles
To access a custom style with basemap styles service, you set the basemap parameter to the item ID for the style created with the Vector Tile Style Editor. Custom basemap styles use the same ArcGIS and OSM vector tiles as the default styles use, except your custom style definitions are applied.
Here is an example of the URL:
- Item id:
d2ff12395aeb45998c1b154e25d680e5 - URL:
https://basemaps-api.arcgis.com/arcgis/rest/services/styles/d2ff12395aeb45998c1b154e25d680e5?type=style&token=< ACCESS_ TOKEN>
Code examples
Get a basemap style with type style
Get the ArcGIS: basemap style definition with the type=style. This is typically used by non-ArcGIS APIs.
https://basemaps-api.arcgis.com/arcgis/rest/services/styles/ArcGIS:DarkGray/?type=style&token=<ACCESS_TOKEN>{
"version": 8,
"sprite": "https://cdn.arcgis.com/sharing/rest/content/items/5e9b3685f4c24d8781073dd928ebda50/resources/styles/../sprites/sprite?token=<YOUR_API_KEY>",
"glyphs": "https://basemaps-api.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer/resources/fonts/{fontstack}/{range}.pbf?token=<YOUR_API_KEY>",
"sources": {
"esri": {
"type": "vector",
"url": "https://basemaps-api.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer?token=<YOUR_API_KEY>",
"minzoom": 0,
"maxzoom": 16,
"tiles": [
"https://basemaps-api.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer/tile/{z}/{y}/{x}.pbf?token=<YOUR_API_KEY>"
],
"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",
Get a basemap style with type webmap
Get the ArcGIS: basemap style definition with type=webmap. Typically used by ArcGIS APIs.
https://basemaps-api.arcgis.com/arcgis/rest/services/styles/ArcGIS:DarkGray/?type=webmap&token=<ACCESS_TOKEN>{
"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 service URL
Vector tiles are served as PBF (Protocolbuffer Binary Format) tiles from https:.
Vector tiles contain static vector data which is rendered on the client using the basemap style definition.
Template URL for ArcGIS provider tiles:
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:
https://basemaps-api.arcgis.com/arcgis/rest/services/OpenStreetMap_v2/VectorTileServer/tile/{z}/{y}/{x}.pbf?token=<ACCESS_TOKEN>Template URL for ArcGIS provider tiles:
https://basemaps.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer/tile/{z}/{y}/{x}.pbf?token=<ACCESS_TOKEN>Template URL for OSM provider tiles:
https://basemaps.arcgis.com/arcgis/rest/services/OpenStreetMap_v2/VectorTileServer/tile/{z}/{y}/{x}.pbf?token=<ACCESS_TOKEN>Learn more about standard and enhanced endpoints in Service endpoints.
Image tile service URL
Image tiles are pre-rendered and are served as images from https:. Tiles are typically 256x256 pixel, 96 ppi PNG or JPEG images.
To read metadata about an image tile service, including the tiling scheme, visit the service root page:
https://ibasemaps-api.arcgis.com/arcgis/rest/services/{serviceName}/MapServer?token=<ACCESS_TOKEN>Template URL examples:
https://ibasemaps-api.arcgis.com/arcgis/rest/services/Ocean/World_Ocean_Base/MapServer/tile/{z}/{y}/{x}?token=<ACCESS_TOKEN>https://ibasemaps-api.arcgis.com/arcgis/rest/services/Elevation/World_Hillshade/MapServer/tile/{z}/{y}/{x}?token=<ACCESS_TOKEN>https://ibasemaps-api.arcgis.com/arcgis/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}?token=<ACCESS_TOKEN>Learn more about standard and enhanced endpoints in Service endpoints.
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 hosted layer (items) and data services.
- User authentication (formerly _ArcGIS identity): 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.
- App credential authentication: Grants a short-lived token, generated via OAuth 2.0, authorizing your application access to ready-to-use services. See usage restrictions.
Learn more about getting access tokens in Security and authentication.
API support
- 1. 2D only
Pricing
To determine how much it costs to access the service:
- If you have an ArcGIS Developer account, go to Pricing. Transactions are billed in US dollars. A free tier of transactions may be available.
- If you have an ArcGIS Online account, go to Understand credits. Transactions are billed in credits.
Service data
Data providers
The data sources contributing to a basemap service layer depend on the layer. To view a list of providers, go to each item in the World basemaps for developers group.
Attribution
Basemap attribution is required when you build and deploy an application which uses the Basemap styles 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
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.
