The basemap styles service v2 is now in beta

We are pleased to announce the basemap styles service v2 is now in beta.

With this version, you can access all of the map styles you did with the basemap styles service (v1), but now there are more options.

Here’s what’s new:  

• A new URL endpoint that provides easy access to all styles and web maps.
• New map styles have been added such as ArcGIS Outdoor and OSM Navigation (light and dark modes). 
• Place label localization is now an option!

If you want to try the new service, go to the Early Adopter program to get started.

To learn more about the service, resources, and the types of apps you can build, keep reading! 

Accessing the service

To access the service, you need the following: 

1. ArcGIS account: You need either an ArcGIS Developer account or an ArcGIS Online account. If you don’t have one, you can sign up for a free account here.

2. Access token:  You will need an access token, such as an API key. If you are using API keys, there isn’t a new API key scope for the service.

3. Client API: For this release, the ArcGIS Maps SDKs do not support the new service quite yet. You can still display the basemap layers however by accessing the endpoints directly with vector tile layers, or you can use the MapLibre GL JS or OpenLayers libraries. ArcGIS Maps SDK support is coming soon!

New developer resources

As part of the release, we added content to the Mapping APIs and location services guide, which contains code and example applications demonstrating how to access the service. There is also a brand new REST API reference  that documents all of the URL endpoints and styles.

New URL endpoint

The basemap styles service v2 has a new URL endpoint that is more RESTful. Similar to the basemap styles service v1, you can return the style as either web map JSON or JSON based on the Mapbox style specification.  

To reference a style, you set arcgis or osm as the provider, webmaps or styles as the response JSON, and the basemap style you want. For example:

Style JSON

https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/arcgis/outdoor
?token=<ACCESS_TOKEN>

Web map JSON

https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/webmaps/arcgis/outdoor
?token=<ACCESS_TOKEN>

To see a complete list of basemap styles available, go to the API reference.

New map styles

With this release, you have access to new map styles such as ArcGIS Outdoor and OSM navigation.

ArcGIS Outdoor

const map = new maplibregl.Map({
  container: "map",
  style: "https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/arcgis/outdoor?token=<ACCESS_TOKEN>",
  zoom: 13,
  center: [-119.52, 37.74] // Starting location [longitude, latitude]
});

OSM Navigation

const map = new maplibregl.Map({
  container: "map", 
  style: "https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/osm/navigation?token=<ACCESS_TOKEN>",
  zoom: 13,
  center: [-119.52, 37.74]
});

To get the code and view the new styles, go to the tutorials in the MapLibre GL JS and OpenLayers guides.

Localized place labels

Another key feature of the new service is the ability to localize place labels for any basemap style. All you need to do is affix the language parameter to the URL request and set one of the 30 available language codes. You can also set language to local to automatically switch to the local language as you navigate to different parts of the world.

Place labels in Japanese

const map = new maplibregl.Map({
  container: "map", 
  style: "https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/arcgis/light-gray
?token=<ACCESS_TOKEN>&language=ja",
  zoom:3,
  center: [138.25, 36.20]
});

Ready to give it a try?

To start building apps with the new service, head over to the Early Adopter program. We look forward to your feedback!

About the authors

Anita Kemp

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

Allan

Allan Laframboise is the product engineering lead for documentation for the Developer Experience team.