The new ArcGIS basemap layer service
Steps to update your applications
Follow these steps to replace the legacy services with the new basemap service:
1. Identify the legacy basemap services
If your application uses any of the URL endpoints below, then you need to update your application.
2. Get an ArcGIS account
3. Get an API key
Log in to the developer dashboard and get an API key (access token).
4. Reference the new services
Use your API key to access the new basemap layer service. Use the URL endpoints below or go to the specific code examples for Leaflet, Mapbox, and OpenLayers.
Image tiles
To access the new image tiles directly for satellite imagery, ocean, or hillshade, use the URL below with {z},{y},and {x} values and a token.
https://ibasemaps-api.arcgis.com/arcgis/rest/services/{ImageryType}/MapServer/tile/{z}/{y}/{x}?token={ACCESS_TOKEN}
Examples
https://ibasemaps-api.arcgis.com/arcgis/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}?token={ACCESS_TOKEN}
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}Vector tiles
basemapStyle, type, and token (either an API key or OAuth 2.0 token). The type should be set to style.https://basemaps-api.arcgis.com/arcgis/rest/services/styles/{basemapStyle}?type={type}&token={ACCESS_TOKEN}
Examples
https://basemaps-api.arcgis.com/arcgis/rest/services/styles/ArcGIS:Navigation?type={type}&token={ACCESS_TOKEN}
https://basemaps-api.arcgis.com/arcgis/rest/services/styles/OSM:Standard?type={type}&token={ACCESS_TOKEN}
https://basemaps-api.arcgis.com/arcgis/rest/services/styles/ArcGIS:Streets?type={type}&token={ACCESS_TOKEN}
https://basemaps-api.arcgis.com/arcgis/rest/services/styles/ArcGIS:Imagery?type={type}&token={ACCESS_TOKEN}
How to update Leaflet and Esri Leaflet apps
The easiest way to update Leaflet applications is to use the Esri Leaflet plugin. You need to load the Esri Leaflet CDN or npm package as well as the Esri Leaflet Vector Plugin.
NOTE: If you already use the Esri Leaflet API with the L.Esri.BasemapLayer class, you need to use the L.esri.Vector.vectorBasemapLayer plugin since the L.Esri.BasemapLayer class is deprecated.
After the libraries are loaded, you can use your API key to access all of the basemap layer styles available.
Learn more in the Esri Leaflet and location services developer guide.
Example
<script src="https://unpkg.com/esri-leaflet@3.0.3/dist/esri-leaflet.js"integrity="sha512-kuYkbOFCV/SsxrpmaCRMEFmqU08n6vc+TfAVlIKjR1BPVgt75pmtU9nbQll+4M9PN2tmZSAgD1kGUCKL88CscA=="crossorigin=""></script>
<script src="https://unpkg.com/esri-leaflet-vector@3.1.1/dist/esri-leaflet-vector.js"integrity="sha512-7rLAors9em7cR3/583gZSvu1mxwPBUjWjdFJ000pc4Wpu+fq84lXF1l4dbG4ShiPQ4pSBUTb4e9xaO6xtMZIlA=="crossorigin=""></script>
const apiKey = "YOUR_API_KEY";
const basemapEnum = "ArcGIS:Navigation";
const map = L.map('map', {
minZoom: 2
}).setView([25,-10], 2); //Latitude, longitude
L.esri.Vector.vectorBasemapLayer(basemapEnum, {
apiKey: apiKey
}).addTo(map);
How to update Mapbox GL JS apps
If you are using an earlier version of Mapbox GL JS (version 1.x), you can access new ArcGIS basemap layer service directly. Replace the old URL endpoints with the new vector tile layer endpoints and include your API key.
Learn more in the Mapbox GL JS and ArcGIS location services guide.
Example
<script src="https://api.tiles.mapbox.com/mapbox-gl-js/v1.12.0/mapbox-gl.js"></script>
<link href="https://api.tiles.mapbox.com/mapbox-gl-js/v1.12.0/mapbox-gl.css" rel="stylesheet"/>
const apiKey = "YOUR_API_KEY";
const basemapEnum = "ArcGIS:Nova"; // Basemap layer style
const map = new mapboxgl.Map({
container: "map",
style: "https://basemaps-api.arcgis.com/arcgis/rest/services/styles/" + basemapEnum+ "?type=style&token=" + apiKey;",
zoom: 1,
center: [-5, 30] // [longitude, latitude]
});
How to update OpenLayers apps
If you are using the OpenLayers API with the TileLayer class or another plug-in such as the OL-Mapbox-Style library, then update to the new URL endpoints to use your API key.
Learn more in the OpenLayers and ArcGIS location services guide.
Example
<link rel="stylesheet" href="https://cdn.jsdelivr.net/gh/openlayers/openlayers.github.io@master/en/v6.7.0/css/ol.css" type="text/css" />
<script src="https://cdn.jsdelivr.net/gh/openlayers/openlayers.github.io@master/en/v6.7.0/build/ol.js"></script>
<script src="https://cdn.jsdelivr.net/npm/ol-mapbox-style@6.1.4/dist/olms.js"></script>
const apiKey = "YOUR_API_KEY";
const basemapId = "ArcGIS:Topographic";
const basemapURL = "https://basemaps-api.arcgis.com/arcgis/rest/services/styles/" + basemapId + "?type=style&token=" + apiKey;
olms(map, basemapURL); //OpenLayers Mapbox style
Summary
The legacy ArcGIS Online tile services have been in mature status for some time now, so to ensure uninterrupted service access, and to comply with Esri’s Terms of Use, you need to update to the new ArcGIS basemap layer service before April 30, 2022.
Also, if you are interested in using other ArcGIS location services such as geocoding or routing with open source APIs, visit the Mapping APIs and location service guide.
Please let us know if you have any questions or concerns.
Article Discussion: