Basemap styles service v2 (beta)

The basemap styles service is a ready-to-use location service that serves vector and image tiles that represent geographic features around the world. It includes styles that represent topographic features, road networks, footpaths, building footprints, water features, administrative boundaries, and satellite imagery. The styles are returned as JSON based on the Mapbox Style Specification or the ArcGIS Web Map Specification. The service also supports localized language place labels. It can also access custom styles stored in ArcGIS.

This documentation is the REST API reference for the service endpoint, requests, parameters, and supported types.

Get started

You can use the service to display:

  • Streets and navigation styles
  • Imagery, oceanic, and topographic styles
  • OSM standard and streets styles
  • Creative styles such as nova and blue print
  • Localized place labels

Need an account?

Sign up for a free ArcGIS account

basemap styles image

To learn how to access the service with ArcGIS, open source, and scripting APIs, go to the Mapping APIs and location services guide.

Service URL

The service supports two different endpoints. One returns JSON for the style based on the Mapbox Style Specification and the other returns JSON for the web map based on the ArcGIS Web Map Specification.

Use dark colors for code blocksCopy
 
1
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles

Requests

To access each basemap style, use the service URL with the desired data source and style.

Use dark colors for code blocksCopy
 
1
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/{data_source}/{style}

ArcGIS styles

Below are the style and web map requests for the ArcGIS data source styles.

Use dark colors for code blocksCopy
 
1
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/arcgis/{style}
Use dark colors for code blocksCopy
 
1
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/webmaps/arcgis/{style}

Learn more about each style in the tables below:

Streets and navigation

Name Layer sources View in ArcGIS
Navigation Single
Navigation (night) Single
Streets Single
Streets relief Multiple
Streets relief base Single
Streets (night) Single

Topography and Imagery

Name Layer sources View in ArcGIS
Outdoor Multiple
Imagery Multiple
Imagery standard Single
Imagery labels Single
Topographic Multiple
Topographic base Single
Terrain Multiple
Terrain base Single
Terrain detail Single
Oceans Multiple
Oceans base Single
Oceans labels Single
Hillshade (dark) Single
Hillshade (light) Single

Reference

Name Layer sources View in ArcGIS
Dark gray Multiple
Dark gray base Single
Dark gray labels Single
Light gray Multiple
Light gray base Single
Light gray labels Single

Creative

OSM styles

Below are the style and web map requests for the OSM data source styles.

Use dark colors for code blocksCopy
 
1
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/osm/{style}
Use dark colors for code blocksCopy
 
1
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/webmaps/osm/{style}

Learn more about each style in the tables below:

Streets and navigation

Name Layer sources View in ArcGIS
Standard Single
Standard relief Multiple
Standard relief base Single
Navigation Single
Navigation (dark) Single
Streets Single
Streets relief Multiple
Streets relief base Single

Imagery

Name Layer sources View in ArcGIS
Imagery hybrid Multiple
Imagery hybrid detail Single
Imagery hybrid reference detail Single

Reference

Name Layer sources View in ArcGIS
Dark gray Multiple
Dark gray base Single
Dark gray labels Single
Light gray Multiple
Light gray base Single
Light gray labels Single

Creative

Name Layer sources View in ArcGIS
Blueprint Single

Custom styles

You can also access custom styles with the service. Styles are stored in ArcGIS as items.

Use dark colors for code blocksCopy
 
1
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/items/{item_id}

Authentication

To access the basemap styles service, you need an ArcGIS Developer account or ArcGIS Online account and you need to use one of the following authentication methods:

  • API key: A permanent token that grants your application access to ready-to-use services. The API key must include the basemaps scope.

  • ArcGIS Identity (formerly named user): A short-lived token, generated via OAuth 2.0, giving your application permission to access the service authorized to an existing ArcGIS user's account.

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

The place labels in ArcGIS basemap styles are, by default, rendered with global place names. By default, place labels in OpenStreetMap basemap styles are localized. To customize the language settings for a basemap style, set the language parameter in the URL request to one of the language codes from the table below:

LanguageESRI Language CodeISO 639-2:1998ISO 639-1Notes
GlobalglobalUses global place names. This default option will use the basemap style default, usually English.
LocallocalUses the local place names. This will use the names of places in their local language - Eg. Lisboa for Lisbon.
ArabicararaUses the Unicode font.
BosnianbsbosUses the Unicode font.
Catalancacat
Chinese (Hong Kong)zh_hkzh-hkUses the Unicode font.
Chinese (Simplified)zh_szh-cnUses the Unicode font.
Chinese (Taiwan)zh_twzh-twUses the Unicode font.
CroatianhrhrvUses the Unicode font.
CzechcsczeUses the Unicode font.
Danishdadan
DutchnldutUses the Unicode font.
Englisheneng
Estonianetest
Finnishfifin
Frenchfrfre
Germandeger
GreekelgreUses the Unicode font.
HebrewhehebUses the Unicode font.
Hungarianhuhun
Indonesianidind
Italianitita
JapanesejajpnUses the Unicode font.
KoreankokorUses the Unicode font.
Latvianlvlav
Lithuanianltlit
Norwegiannonor
Polishplpol
Portuguese (Brazil)pt_brpt-br
Portuguese (Portugal)pt_ppt
RomanianrorumUses the Unicode font.
RussianrurusUses the Unicode font.
SerbiansrsrpUses the Unicode font.
Spanishesspa
Swedishsvswe
ThaiththaUses the Unicode font.
Turkishtrtur
UkrainianukukrUses the Unicode font.
Vietnamesevivie

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.

API support

Full supportPartial supportNo support

    Limitations

    The service can only be accessed by the supported APIs above. To access basemap layers with additional APIs, go to Basemap styles service (v1).

    Pricing

    Terms of use

    You cannot store basemap style service tiles or data for future use. To see a complete description of the allowable usage, attribution, and usage rules, please see the Terms of use.

    Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.