Learn how to change language labels for styled basemap tiles.
The ArcGIS Static Basemap Tiles servicenavigation, streets, outdoor, and light-gray. The tiles are returned as PNG files.
In this tutorial, you use the dropdown menu to toggle between different languages for the static basemap tiles.
Prerequisites
You need an ArcGIS Location Platform account.
ArcGIS Online and ArcGIS Enterprise accounts are not supported.
Steps
Get the starter app
Select a type of authentication and follow the steps to create a new app.
Choose API key authentication if you:
- Want the easiest way to get started.
- Want to build public applications
A public application is an application that allows anonymous access without requiring users to sign in with an ArcGIS account. It supports API key or app authentication. that access ArcGIS Location ServicesArcGIS Location Services, also referred to as Location Services, are services hosted by Esri that provide geospatial functionality for developing mapping applications. They include the ArcGIS Basemap Styles service, ArcGIS Static Basemap Tiles service, ArcGIS Places service, ArcGIS Geocoding service, ArcGIS Routing service, ArcGIS GeoEnrichment service, and ArcGIS Elevation service. An ArcGIS Location Platform or ArcGIS Online account is required to use the services. and secure itemsAn item, also known as a content item, is a resource stored in a portal such as a web map, hosted layer, style, script tool, file, or notebook. . - Have an ArcGIS Location Platform or ArcGIS Online account.
Choose user authentication if you:
- Want to build private applications.
- Require application users to sign in with their own ArcGIS account
An ArcGIS account is an identity with a user type and set of privileges that can access specific ArcGIS products, tools, APIs, services, and resources. The main account types that can be used for development are an ArcGIS Location Platform account, ArcGIS Online account, and ArcGIS Enterprise account. ArcGIS Location Platform and ArcGIS Online accounts are also associated with a subscription. and access resources their behalf. - Have an ArcGIS Online account.
To learn more about both types of authentication, go to Authentication.
Set up authentication
Set developer credentials
Get a Cesium ion access token
All Cesium applications must use an access token provided through Cesium ion. This token allows you to access assets such as Cesium World Terrain in your application.
-
Go to your Cesium ion dashboard to generate an access token. Copy the key to your clipboard.
-
Create a
cesiumvariable and replaceAccess Token YOURwith the access token you copied from the Cesium ion dashboard._CESIUM _ACCESS _TOKEN Use dark colors for code blocks <script> /* Use for API key authentication */ const accessToken = "YOUR_ACCESS_TOKEN"; // or /* Use for user authentication */ // const session = await arcgisRest.ArcGISIdentityManager.beginOAuth2({ // clientId: "YOUR_CLIENT_ID", // Your client ID from OAuth credentials // redirectUri: "YOUR_REDIRECT_URI", // The redirect URL registered in your OAuth credentials // portal: "YOUR_PORTAL_URL" // Your portal URL // }) // const accessToken = session.token; Cesium.ArcGisMapService.defaultAccessToken = accessToken; const cesiumAccessToken = "YOUR_CESIUM_ACCESS_TOKEN"; </script> -
Configure
Cesium.with the Cesium access token to validate the application.Ion.default Access Token Use dark colors for code blocks <script> /* Use for API key authentication */ const accessToken = "YOUR_ACCESS_TOKEN"; // or /* Use for user authentication */ // const session = await arcgisRest.ArcGISIdentityManager.beginOAuth2({ // clientId: "YOUR_CLIENT_ID", // Your client ID from OAuth credentials // redirectUri: "YOUR_REDIRECT_URI", // The redirect URL registered in your OAuth credentials // portal: "YOUR_PORTAL_URL" // Your portal URL // }) // const accessToken = session.token; Cesium.ArcGisMapService.defaultAccessToken = accessToken; const cesiumAccessToken = "YOUR_CESIUM_ACCESS_TOKEN"; Cesium.Ion.defaultAccessToken = cesiumAccessToken; </script>
Add a language selector
Add a menu that allows users to change the display language of your map. CesiumJS does not have a built-in selector widget, so you will create an HTML <select element.
-
In the
<bodyelement, add a> selectelement, which you will populate in a later step.Use dark colors for code blocks <body> <div id="cesiumContainer"></div> <div id="language-wrapper"> <select id="language"></select> </div> </body> -
In the
<headtag, add CSS that will position the> <selectmenu element and its wrapper in the upper right corner and provide styling.> Use dark colors for code blocks <style> html, body, #cesiumContainer { margin: 0; padding: 0; width: 100%; height: 100%; } #language-wrapper { position: absolute; top: 20px; left: 20px; background: rgba(255, 255, 255, 0); } #language { font-size: 16px; padding: 4px 8px; } </style>
Update the camera's viewpoint
-
Change the camera's
destinationto8.20, 46.90, 300000. This will focus the camera on Switzerland.Use dark colors for code blocks Copy viewer.camera.setView({ destination: Cesium.Cartesian3.fromDegrees(8.20, 46.90, 250000) });
Set the basemap language
When the scene loads, initialize the app to display the basemap in English.
-
Create a function called
urlthat takes a language as a parameter. This will create the URL of the static basemap tiles for that specified language.Use dark colors for code blocks const basemapEnum = "arcgis/navigation"; const baseUrl = "https://static-map-tiles-api.arcgis.com/arcgis/rest/services/static-basemap-tiles-service/v1"; const url = (language) => `${baseUrl}/${basemapEnum}/static/tile/{z}/{y}/{x}?token=${accessToken}&language=${language}`; -
Create a
defaultvariable for the basemap, which isLanguage enfor English.Use dark colors for code blocks const basemapEnum = "arcgis/navigation"; const baseUrl = "https://static-map-tiles-api.arcgis.com/arcgis/rest/services/static-basemap-tiles-service/v1"; const url = (language) => `${baseUrl}/${basemapEnum}/static/tile/{z}/{y}/{x}?token=${accessToken}&language=${language}`; const defaultLanguage = "en"; -
Import
arcgisto make a request to the Static Basemap Tiles service. This dynamically fetches the available basemap languages and populates theRest.request() selectelement.Use dark colors for code blocks <!-- ArcGIS REST JS --> <script src="https://unpkg.com/@esri/arcgis-rest-request@4/dist/bundled/request.umd.js"></script>Use dark colors for code blocks const selector = document.querySelector("#language"); arcgisRest.request(`${baseUrl}/self`, { httpMethod: "GET", authentication: arcgisRest.ApiKeyManager.fromKey(accessToken) }).then((response) => { response.languages.forEach((language) => { const option = document.createElement("option"); option.value = language.code; option.textContent = language.name; selector.appendChild(option); }); }); -
Fetch the service URL to retrieve the basemap JSON. Then, create an
Urlobject from the JSON.Template Imagery Provider Use dark colors for code blocks arcgisRest.request(`${baseUrl}/${basemapEnum}/static`, { httpMethod: "GET", authentication: arcgisRest.ApiKeyManager.fromKey(accessToken) }).then((data) => { const imageryProvider = new Cesium.UrlTemplateImageryProvider({ url: url(defaultLanguage), tileHeight: 512, }); }); -
Remove the basemap attribution code because you will add it dynamically instead in the next step.
Use dark colors for code blocks fetch(`${baseUrl}?token=${accessToken}`) .then((response) => response.json()) .then((data) => { const basemapAttribution = new Cesium.Credit(data.copyrightText, false); viewer.creditDisplay.addStaticCredit(basemapAttribution); }); -
Create a
basemapand instantiate aCredit Creditobject from thecopyrightstring of the JSON. CesiumJS does not provide attribution automatically for Static Basemap Tiles serviceText The ArcGIS Static Basemap Tiles service, also known as the Static Basemap Tiles service, is a location service that provides basemap data as pre-rendered and pre-styled map tiles for the world. It supports key styles in the ArcGIS Basemap style family. An ArcGIS Location Platform account is required to use the services. . Therefore, you are required to add this attribution manually.Use dark colors for code blocks let basemapCredit; const selector = document.querySelector("#language"); arcgisRest.request(`${baseUrl}/self`, { httpMethod: "GET", authentication: arcgisRest.ApiKeyManager.fromKey(accessToken) }).then((response) => { response.languages.forEach((language) => { const option = document.createElement("option"); option.value = language.code; option.textContent = language.name; selector.appendChild(option); }); }); arcgisRest.request(`${baseUrl}/${basemapEnum}/static`, { httpMethod: "GET", authentication: arcgisRest.ApiKeyManager.fromKey(accessToken) }).then((data) => { basemapCredit = data.copyrightText; const imageryProvider = new Cesium.UrlTemplateImageryProvider({ url: url(defaultLanguage), tileHeight: 512, credit: basemapCredit }); }); -
Add the
imageryto the viewer.Provider Use dark colors for code blocks arcgisRest.request(`${baseUrl}/${basemapEnum}/static`, { httpMethod: "GET", authentication: arcgisRest.ApiKeyManager.fromKey(accessToken) }).then((data) => { basemapCredit = data.copyrightText; const imageryProvider = new Cesium.UrlTemplateImageryProvider({ url: url(defaultLanguage), tileHeight: 512, credit: basemapCredit }); viewer.imageryLayers.addImageryProvider(imageryProvider); }); -
Run the code to ensure that the
<selectelement contains different language enumerations.>
Add an event listener
-
Add an event listener for the selector.
Use dark colors for code blocks selector.addEventListener("change", (e) => { }); -
Create a new
Urlusing the selected language.Template Imagery Provider Use dark colors for code blocks selector.addEventListener("change", (e) => { const newImageryProvider = new Cesium.UrlTemplateImageryProvider({ url: url(e.target.value), tileWidth: 512, tileHeight: 512, credit: basemapCredit }); }); -
Update the viewer with the new language.
Use dark colors for code blocks selector.addEventListener("change", (e) => { const newImageryProvider = new Cesium.UrlTemplateImageryProvider({ url: url(e.target.value), tileWidth: 512, tileHeight: 512, credit: basemapCredit }); viewer.imageryLayers.removeAll(); viewer.imageryLayers.addImageryProvider(newImageryProvider); });
Run the app
Run the app.
The map should be displayed in English and you should be able to use the controls to switch between language labels.What's next?
Learn how to use additional location services in these tutorials:

