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 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).
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.
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styleshttps://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/webmapsRequests
To access each basemap style, use the service URL with the desired data source and style.
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/{data_source}/{style}https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/webmaps/{data_source}/{style}ArcGIS styles
Below are the style and web map requests for the ArcGIS data source styles.
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/arcgis/{style}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 | API reference | Example |
|---|---|---|
Navigation |
|  |
Navigation (night) |
|  |
Streets |
|  |
Streets relief |
|  |
Streets relief base |
|  |
Streets (night) |
|  |
Topography and Imagery
| Name | API reference | Example |
|---|---|---|
Outdoor |
|  |
Imagery |
|  |
Imagery standard |
|  |
Imagery labels |
|  |
Topographic |
|  |
Topographic base |
|  |
Terrain |
|  |
Terrain base |
|  |
Terrain detail |
|  |
Oceans |
|  |
Oceans base |
|  |
Oceans labels |
|  |
Hillshade (dark) |
|  |
Hillshade (light) |
|  |
Reference
| Name | API reference | Example |
|---|---|---|
Dark gray |
|  |
Dark gray base |
|  |
Dark gray labels |
|  |
Light gray |
|  |
Light gray base |
|  |
Light gray labels |
|  |
Creative
| Name | API reference | Example |
|---|---|---|
Human geography |
|  |
Human geography (base) |
|  |
Human geography detail |
|  |
Human geography labels |
|  |
Human geography dark |
|  |
Human geography dark base |
|  |
Human geography dark detail |
|  |
Human geography dark labels |
|  |
Colored pencil |
|  |
Community |
|  |
Nova |
|  |
Charted territory |
|  |
Charted territory base |
|  |
Midcentury |
|  |
Newspaper |
|  |
Modern antique |
|  |
Modern antique base |
|  |
OSM styles
Below are the style and web map requests for the OSM data source styles.
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/osm/{style}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 | API reference | Example |
|---|---|---|
Standard |
|  |
Standard relief |
|  |
Standard relief base |
|  |
Navigation |
|  |
Navigation (dark) |
|  |
Streets |
|  |
Streets relief |
|  |
Streets relief base |
|  |
Imagery
| Name | API reference | Example |
|---|---|---|
Hybrid |
|  |
Imagery hybrid detail |
|  |
Reference
| Name | API reference | Example |
|---|---|---|
Dark gray |
|  |
Dark gray base |
|  |
Dark gray labels |
|  |
Light gray |
|  |
Light gray base |
|  |
Light gray labels |
|  |
Creative
| Name | API reference | Example |
|---|---|---|
Blueprint |
|  |
Custom styles
You can also access custom styles with the service. Styles are stored in ArcGIS as items.
https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/styles/items/{item_id}https://basemapstyles-api.arcgis.com/arcgis/rest/services/styles/v2/webmaps/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.
-
User authentication (formerly ArcGIS Identity): A short-lived access token, generated via OAuth 2.0, giving your application permission to access the service authorized to an existing ArcGIS user's account.
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
https://basemaps-api.arcgis.com/arcgis/rest/services/World_Basemap_v2/VectorTileServer?token=<ACCESS_TOKEN>https://basemaps-api.arcgis.com/arcgis/rest/services/OpenStreetMap_v2/VectorTileServer?token=<ACCESS_TOKEN>https://basemaps.arcgis.com/arcgis/rest/services/World_Contours_v2/VectorTileServer?token=<ACCESS_TOKEN>https://basemaps.arcgis.com/arcgis/rest/services/World_Hillshade_v2/VectorTileServer?token=<ACCESS_TOKEN>Map tile services
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>https://ibasemaps-api.arcgis.com/arcgis/rest/services/Elevation/World_Hillshade_Dark/MapServer/tile/{z}/{y}/{x}?token=<ACCESS_TOKEN>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:
| Language | ESRI Language Code | ISO 639-2:1998 | ISO 639-1 | Notes |
|---|---|---|---|---|
| Global | global | Uses global place names. This default option will use the basemap style default, usually English. | ||
| Local | local | Uses the local place names. This will use the names of places in their local language - Eg. Lisboa for Lisbon. | ||
| Arabic | ar | ara | Uses the Unicode font. | |
| Bosnian | bs | bos | Uses the Unicode font. | |
| Catalan | ca | cat | ||
| Chinese (Hong Kong) | zh-HK | zh-hk | Uses the Unicode font. | |
| Chinese (Simplified) | zh-CN | zh-cn | Uses the Unicode font. | |
| Chinese (Taiwan) | zh-TW | zh-tw | Uses the Unicode font. | |
| Croatian | hr | hrv | Uses the Unicode font. | |
| Czech | cs | cze | Uses the Unicode font. | |
| Danish | da | dan | ||
| Dutch | nl | dut | Uses the Unicode font. | |
| English | en | eng | ||
| Estonian | et | est | ||
| Finnish | fi | fin | ||
| French | fr | fre | ||
| German | de | ger | ||
| Greek | el | gre | Uses the Unicode font. | |
| Hebrew | he | heb | Uses the Unicode font. | |
| Hungarian | hu | hun | ||
| Indonesian | id | ind | ||
| Italian | it | ita | ||
| Japanese | ja | jpn | Uses the Unicode font. | |
| Korean | ko | kor | Uses the Unicode font. | |
| Latvian | lv | lav | ||
| Lithuanian | lt | lit | ||
| Norwegian | nb | nor | ||
| Polish | pl | pol | ||
| Portuguese (Brazil) | pt-BR | pt-br | ||
| Portuguese (Portugal) | pt-PT | pt | ||
| Romanian | ro | rum | Uses the Unicode font. | |
| Russian | ru | rus | Uses the Unicode font. | |
| Serbian | sr | srp | Uses the Unicode font. | |
| Spanish | es | spa | ||
| Swedish | sv | swe | ||
| Thai | th | tha | Uses the Unicode font. | |
| Turkish | tr | tur | ||
| Ukrainian | uk | ukr | Uses the Unicode font. | |
| Vietnamese | vi | vie |
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
- 1. Access with the basemap style URL to return JSON based on the ArcGIS Web Map Specification.
Limitations
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/navigationandarcgis/navigation-nightare supported. - Icons and locations: Displaying places in North America with
places=allvsplaces=attributedwill result in some icon and location differences. - MapLibre JS: When using MapLibre JS with
places=allorplaces=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=allorplaces=attributedparameter. To authenticate requests, an access token is required. It is also not possible to perform ahitto access place features.Test
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.