Developers

Open source developers: Time to upgrade to the new ArcGIS basemap layer service!

If you have built a mapping application with an open source client API such as Leaflet, Esri Leaflet, Openlayers, or Mapbox, that uses the legacy ArcGIS Online tile services, then it’s time to update to the new ArcGIS basemap layer service!
The legacy ArcGIS Online tile services are in mature status and are no longer being updated. So to ensure uninterrupted access and to comply with Esri’s Terms of Use, applications need to be updated before April 30, 2022.
The good news is that updating is easy and you can still access basemap services for free!

The new ArcGIS basemap layer service

The new ArcGIS basemap layer service replaces the legacy ArcGIS Online tile services. The new service provides much better performance, especially for applications accessed from different countries around the world, and it also provides higher resolution satellite imagery for new geographic regions.
We also encourage you to use the new vector tile basemap service. The service supports the Mapbox Vector Tile Specification and is easy to integrate with open source APIs. Vector tiles provide the best overall performance and you can choose from over 25 vector tile styles for your applications.
The vector tile service also supports creating your own basemap styles with the Vector Tile Style Editor, so you can brand your applications with custom colors, fonts, and glyphs. Learn how to create custom styles in the Create a custom style tutorial.

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

To use the new basemap layer service, you need an ArcGIS Developer (for individual developers) or ArcGIS Online account (for organizations). If you don’t have one, you can sign up for free.
NOTE: A developer account gives you access to 2,000,000 basemap tiles for free per month.

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

To access the new vector tile styles, use the URL below with the 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.

About the authors

Allan

Allan Laframboise is a software engineer and documentation lead on the Developer Experience team.

Anita Kemp

Anita Kemp is a product engineer on the Developer Experience team.

0 Comments
Inline Feedbacks
View all comments

Next Article

Notification that old Esri Vector Basemaps will be retired in 2022

Read this article