Basemap styles service

The basemap styles service is a 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 displaying localized language place labels, places, and worldviews. Custom basemap styles can also be created from the the default styles.

This documentation is the REST API reference for the service endpoint, requests, parameters, and supported types. The API reference is also available with the OpenAPI Specification. To find previous versions, go to basemaps styles service (v1).

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
  • Custom basemap styles
  • Localized place labels
  • Places with styles
  • Worldview boundaries

Need an account?
Sign up for a free ArcGIS account

basemap styles image

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. If you need the underlying vector tile service and image tile service URLs, go to Tile services.

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

NameAPI referenceExample

Navigation

arcgis/navigation

Navigation (night)

arcgis/navigation-night

Streets

arcgis/streets

Streets relief

arcgis/streets-relief

Streets relief base

arcgis/streets-relief/base

Streets (night)

arcgis/streets-night

Topography and Imagery

NameAPI referenceExample

Outdoor

arcgis/outdoor

Imagery

arcgis/imagery

Imagery standard

arcgis/imagery/standard

Imagery labels

arcgis/imagery/labels

Topographic

arcgis/topographic

Topographic base

arcgis/topographic/base

Terrain

arcgis/terrain

Terrain base

arcgis/terrain/base

Terrain detail

arcgis/terrain/detail

Oceans

arcgis/oceans

Oceans base

arcgis/oceans/base

Oceans labels

arcgis/oceans/labels

Hillshade (dark)

arcgis/hillshade/dark

Hillshade (light)

arcgis/hillshade/light

Reference

NameAPI referenceExample

Dark gray

arcgis/dark-gray

Dark gray base

arcgis/dark-gray/base

Dark gray labels

arcgis/dark-gray/labels

Light gray

arcgis/light-gray

Light gray base

arcgis/light-gray/base

Light gray labels

arcgis/light-gray/labels

Creative

NameAPI referenceExample

Human geography

arcgis/human-geography

Human geography (base)

arcgis/human-geography/base

Human geography detail

arcgis/human-geography/detail

Human geography labels

arcgis/human-geography/labels

Human geography dark

arcgis/human-geography-dark

Human geography dark base

arcgis/human-geography-dark/base

Human geography dark detail

arcgis/human-geography/dark/detail

Human geography dark labels

arcgis/human-geography/dark/labels

Colored pencil

arcgis/colored-pencil

Community

arcgis/community

Nova

arcgis/nova

Charted territory

arcgis/charted-territory

Charted territory base

arcgis/charted-territory/base

Midcentury

arcgis/midcentury

Newspaper

arcgis/newspaper

Modern antique

arcgis/modern-antique

Modern antique base

arcgis/modern-antique/base

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

NameAPI referenceExample

Standard

osm/standard

Standard relief

osm/standard-relief

Standard relief base

osm/standard-relief/base

Navigation

osm/navigation

Navigation (dark)

osm/navigation-dark

Streets

osm/streets

Streets relief

osm/streets-relief

Streets relief base

osm/streets-relief/base

Imagery

NameAPI referenceExample

Hybrid

osm/hybrid

Imagery hybrid detail

osm/hybrid/detail

Reference

NameAPI referenceExample

Dark gray

osm/dark-gray

Dark gray base

osm/dark-gray/base

Dark gray labels

osm/dark-gray/labels

Light gray

osm/light-gray

Light gray base

osm/light-gray/base

Light gray labels

osm/light-gray/labels

Creative

NameAPI referenceExample

Blueprint

osm/blueprint

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}

Service access

To access the basemap styles service, you need the following:

Service data

Web maps

The World basemaps for developers group in ArcGIS.com contains the web maps for each basemap style. Go to each web map to learn more about the style description, attribution, data sources, and data providers.

Tile services

The underlying data sources for the basemap styles service are vector and map tile services. To find all of the web maps and/or layers hosted in ArcGIS that provide data for this service, go to World basemaps for developers.

Vector tile services

Use dark colors for code blocksCopy
1
https://basemaps-api.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer?token=<ACCESS_TOKEN>
Use dark colors for code blocksCopy
1
https://basemaps-api.arcgis.com/arcgis/rest/services/OpenStreetMap_v2/VectorTileServer?token=<ACCESS_TOKEN>
Use dark colors for code blocksCopy
1
https://basemaps.arcgis.com/arcgis/rest/services/World_Contours_v2/VectorTileServer?token=<ACCESS_TOKEN>
Use dark colors for code blocksCopy
1
https://basemaps.arcgis.com/arcgis/rest/services/World_Hillshade_v2/VectorTileServer?token=<ACCESS_TOKEN>

Map tile services

Use dark colors for code blocksCopy
1
https://ibasemaps-api.arcgis.com/arcgis/rest/services/Ocean/World_Ocean_Base/MapServer/tile/{z}/{y}/{x}?token=<ACCESS_TOKEN>
Use dark colors for code blocksCopy
1
https://ibasemaps-api.arcgis.com/arcgis/rest/services/Elevation/World_Hillshade/MapServer/tile/{z}/{y}/{x}?token=<ACCESS_TOKEN>
Use dark colors for code blocksCopy
1
https://ibasemaps-api.arcgis.com/arcgis/rest/services/Elevation/World_Hillshade_Dark/MapServer/tile/{z}/{y}/{x}?token=<ACCESS_TOKEN>
Use dark colors for code blocksCopy
1
https://ibasemaps-api.arcgis.com/arcgis/rest/services/World_Imagery/MapServer/tile/{z}/{y}/{x}?token=<ACCESS_TOKEN>

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.
BulgarianbgbulUses the Unicode font.
Catalancacat
Chinese (Hong Kong)zh-HKzh-hkUses the Unicode font.
Chinese (Simplified)zh-CNzh-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
Norwegiannbnor
Polishplpol
Portuguese (Brazil)pt-BRpt-br
Portuguese (Portugal)pt-PTpt
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

Basemap styles service
ArcGIS Maps SDK for JavaScript
ArcGIS Maps SDK for Kotlin1
ArcGIS Maps SDK for Swift1
ArcGIS Maps SDK for .NET1
ArcGIS Maps SDK for Qt1
ArcGIS Maps SDK for Java1
ArcGIS API for Python
ArcGIS REST JS
Esri Leaflet
MapLibre GL JS
OpenLayers
CesiumJS
Full supportPartial supportNo support
  • 1. Access with the basemap style URL to return JSON based on the ArcGIS Web Map Specification.

Limitations

Products and accounts

To access the basemap styles service, you need an ArcGIS Location Platform or ArcGIS Online account.

You cannot access the service with an ArcGIS Enterprise account.

APIs

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

Basemap places

The new places query parameter allows you to display places with basemap styles.

The following are known limitations and issues:

  • Style support: Only arcgis/navigation and arcgis/navigation-night are supported.
  • Icons and locations: Displaying places in North America with places=all vs places=attributed will result in some icon and location differences.
  • MapLibre JS: When using MapLibre JS with places=all or places=attributed, the place symbols may appear incorrectly or intermittently at smaller map scales (zoomed out). However, places will appear correctly at larger map scales (zoomed in to street levels).
  • ArcGIS Maps SDK for JavaScript: To display places with the ArcGIS Maps SDK for JavaScript you need to access the style directly with the places=all or places=attributed parameter. To authenticate requests, an access token is required. It is also not possible to perform a hitTest to access place features.

Worldview

The new worldview query parameter allows you to display country boundaries and labels based on a specific view of a country.

Worldviews can only be specified for key ArcGIS basemap styles (OSM is not supported). When a specific worldview is chosen, it is possible for some labels to change language. However, when the language query parameter is used in combination with the worldview selection, the explicitly selected language will take priority over any language changes associated with the worldview.

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.