Tutorial: Change language labels for static basemap tiles

Learn how to change language labels for static basemap tiles service (beta) .

The static basemap tiles service (beta) provides access to raster basemap tiles for the world. The service supports a number of ArcGIS styles such as navigation, 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

This tutorial requires an ArcGIS Location Platform account.

Steps

Create a new pen

To get started, you can complete the Display a scene tutorial or use the .

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.s

Go to your Cesium ion dashboard to generate an access token. Copy the key and store it somewhere safe.

Get an access token

You need an access token with the correct privileges to access the resources used in this tutorial.

Go to the Create an API key tutorial and create an API key with the following privilege(s):
- Privileges
  - Location services > Basemaps
Copy the API key access token as it will be used in the next step.

To learn about other ways to get an access token, go to Types of authentication.

Set the access tokens

In CodePen, update the accessToken and cesiumAccessToken variables to use the access tokens you have obtained.

Use dark colors for code blocks
    const accessToken = "YOUR_ACCESS_TOKEN"

    const cesiumAccessToken = "YOUR_CESIUM_ACCESS_TOKEN";

    Cesium.Ion.defaultAccessToken = cesiumAccessToken;

    const viewer = new Cesium.Viewer("cesiumContainer", {
      timeline: false,
      animation: false,
      geocoder: false,
    });

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 <body> element, add a select element that contains an enumeration for each language available through the static basemap tiles service (beta).

Use dark colors for code blocks
<body>
  <div id="cesiumContainer"></div>

  <div id="language-wrapper">
    <select id="language">
      <option value="fr">French</option>
      <option value="en">English</option>
      <option value="nl">Dutch</option>
      <option value="da">Danish</option>
      <option value="fi">Finnish</option>
      <option value="de">German</option>
      <option value="nb">Norwegian</option>
    </select>
  </div>

</body>

In the <head> tag, add CSS that will position the <select> menu 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 destination to 8.20, 46.90, 300000. This will focus the camera on Switzerland.

Expand
Use dark colors for code blocks
    viewer.camera.setView({

      destination: Cesium.Cartesian3.fromDegrees(8.20, 46.90, 300000),

      orientation: {
        heading: Cesium.Math.toRadians(0.0),
        pitch: Cesium.Math.toRadians(-90.0),
      }
    });
Expand

Remove base layer references

Remove arcGisImagery, terrain, and the baseLayer properties from the viewer.

Use dark colors for code blocks
      const arcGisImagery = Cesium.ArcGisMapServerImageryProvider.fromBasemapType(Cesium.ArcGisBaseMapType.SATELLITE);

      const viewer = new Cesium.Viewer("cesiumContainer", {

        baseLayer: Cesium.ImageryLayer.fromProviderAsync(arcGisImagery),

        terrain: Cesium.Terrain.fromWorldTerrain(),

        timeline: false,
        animation: false,
        geocoder:false

      });

Set the basemap

When the scene loads, initialize the app to display the static basemap tiles in French.

Create a constant variable called basemapEnum to define the default basemap style. Since the service is still in beta, we will append beta/ before arcgis/outdoor.

Use dark colors for code blocks
    const basemapEnum = 'beta/arcgis/outdoor';

Create a function called url that takes a language as a parameter. This will create the URL of the static basemap tiles for that specified language.

Expand
Use dark colors for code blocks
    const basemapEnum = 'beta/arcgis/outdoor';

    const baseUrl = `https://static-map-tiles-api.arcgis.com/arcgis/rest/services/static-basemap-tiles-service/${basemapEnum}/static`
    const url = (language) => `${baseUrl}/tile/{z}/{y}/{x}?token=${accessToken}&language=${language}`;

Expand

Create a defaultLanguage variable for the basemap, which is fr for French.

Expand
Use dark colors for code blocks
    const basemapEnum = 'beta/arcgis/outdoor';

    const baseUrl = `https://static-map-tiles-api.arcgis.com/arcgis/rest/services/static-basemap-tiles-service/${basemapEnum}/static`
    const url = (language) => `${baseUrl}/tile/{z}/{y}/{x}?token=${accessToken}&language=${language}`;

    const defaultLanguage = "fr";
Expand

Fetch the service URL to retrieve the basemap JSON. Then, create an UrlTemplateImageryProvider object from the JSON.

Expand
Use dark colors for code blocks
    fetch(`${baseUrl}?token=${accessToken}`)
      .then(response => response.json())
      .then(data => {

        const imageryProvider = new Cesium.UrlTemplateImageryProvider({
          url: url(defaultLanguage),
          tileHeight: 512,

        });

      });
Expand

Create a basemapCredit and instantiate a Credit object from the copyrightText string of the JSON. CesiumJS does not provide attribution automatically for static basemap tiles service (beta). Therefore, you are required to add this attribution manually.

Expand
Use dark colors for code blocks
    let basemapCredit;

    fetch(`${baseUrl}?token=${accessToken}`)
      .then(response => response.json())
      .then(data => {

        basemapCredit = data.copyrightText

        const imageryProvider = new Cesium.UrlTemplateImageryProvider({
          url: url(defaultLanguage),
          tileHeight: 512,

          credit: basemapCredit

        });

      });
Expand

Add the imageryProvider to the viewer.

Expand
Use dark colors for code blocks
    fetch(`${baseUrl}?token=${accessToken}`)
      .then(response => response.json())
      .then(data => {

        basemapCredit = data.copyrightText

        const imageryProvider = new Cesium.UrlTemplateImageryProvider({
          url: url(defaultLanguage),
          tileHeight: 512,

          credit: basemapCredit

        });

        viewer.imageryLayers.addImageryProvider(imageryProvider);

      });
Expand

Run the code to ensure the map displays the default static basemap tiles in French and that the <select> element contains different language enumerations.

Add an event listener

Use an event listener to register a language change in the <select> element and to update the scene.

Add an event listener for the #language select element.

Expand
Use dark colors for code blocks
    document.querySelector("#language").addEventListener("change", (e) => {

    });
Expand

Create a new UrlTemplateImageryProvider using the selected language.

Expand
Use dark colors for code blocks
    document.querySelector("#language").addEventListener("change", (e) => {

      const newImageryProvider = new Cesium.UrlTemplateImageryProvider({
        url: url(e.target.value),
        tileWidth: 512,
        tileHeight: 512,
        credit: basemapCredit
      });

    });
Expand

Update the viewer with the new language.

Expand
Use dark colors for code blocks
    document.querySelector("#language").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);

    });
Expand

Run the app

In CodePen, run your code to display the map.

The map should be displayed in French and you should be able to use the controls to switch between language labels.

What's next?

Learn how to use additional ArcGIS location services in these tutorials:

Change the static basemap tiles style

Change the basemap style in a map using the static basemap tiles service (beta).