Display a map with a basemap session (4 of 4)

Use the ArcGIS Geocoding service and ArcGIS REST JS to add search on the app.

Search for an address on the map.

Prerequisites

You need an ArcGIS Location Platform account.
You need to complete Step 3. Change the basemap style.

Steps

Add script references

This tutorial uses ArcGIS REST JS to access the ArcGIS Geocoding service.

In the <head> element, add references to the ArcGIS REST JS request and geocoding libraries.

Use dark colors for code blocks
  <!-- Load ArcGIS REST JS -->
  <script src="https://unpkg.com/@esri/arcgis-rest-request@4/dist/bundled/request.umd.js"></script>
  <script
    src="https://unpkg.com/@esri/arcgis-rest-geocoding@4/dist/bundled/geocoding.umd.js"></script>

Create a REST JS ApiKeyManager using your access token. This object will authorize requests to the Geocoding service later.

Use dark colors for code blocks
    const authentication = arcgisRest.ApiKeyManager.fromKey(accessToken);

Create a `GeocodeControl`

To let users geocode, you can create a custom control that implements MapLibre's IControl.

Create a new GeocodeControl. This control will include an input field where users can type an address they want to geocode on the map.

Expand
Use dark colors for code blocks
    class GeocodeControl {
      onAdd(map) {
        const container = document.createElement("div");
        container.className = "maplibregl-ctrl maplibregl-ctrl-group";

        container.innerHTML = `
          <div id="geocode-container">
            <input id="geocode-input" type="text" placeholder="Type an address or place" autocomplete="off" />
            <button id="clear-button">&times;</button>
          </div>
        `;

        return container;
      }
    }

Expand

In the <body> of your HTML, add a <ul> element with the id suggestions. This list will display location suggestions below the input field.

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

  <ul id="suggestions"></ul>

Add CSS styling to control the layout and appearance of the geocoding control and the suggestions list.

Expand
Use dark colors for code blocks
    #geocode-container {
      display: flex;
      align-items: center;
    }

    #geocode-input {
      padding: 4px 8px;
      width: 20vw;
      border: 0;
    }

    #clear-button {
      border: none;
      color: #666;
      cursor: pointer;
      background-color: #fff;
      z-index: 1;
    }

    #suggestions {
      display: none;
      position: absolute;
      top: 40px;
      left: 10px;
      background: white;
      list-style: none;
      padding: 0;
      margin: 0;
      width: 25vw;
      z-index: 999;
    }

    #suggestions li {
      padding: 6px 8px;
      border: 1px solid transparent;
      box-sizing: border-box;
    }

    #suggestions li:hover {
      background-color: #f0f0f0;
    }

    #suggestions li.selected {
      border-color: #000000;
    }

Expand

Add the GeocodeControl to the top left of your map.

Expand
Use dark colors for code blocks
    class GeocodeControl {
      onAdd(map) {
        const container = document.createElement("div");
        container.className = "maplibregl-ctrl maplibregl-ctrl-group";

        container.innerHTML = `
          <div id="geocode-container">
            <input id="geocode-input" type="text" placeholder="Type an address or place" autocomplete="off" />
            <button id="clear-button">&times;</button>
          </div>
        `;

        return container;
      }
    }

    map.addControl(new GeocodeControl(), "top-left");
Expand

Get address suggestions

Use the suggest method from the geocoding service to fetch location suggestions as a user types.

Add an input event handler to capture text as a user types. Reset the selection index and hide suggestions when the input is empty.

Expand
Use dark colors for code blocks
    const input = document.getElementById("geocode-input");
    const suggestionsList = document.getElementById("suggestions");
    let selectedIndex = -1;

    input.addEventListener("input", () => {
      selectedIndex = -1;
      const text = input.value;

      if (!text) return suggestionsList.style.display = "none";

    });
Expand

Use the suggest method to fetch location suggestions as the user types, then display them in a list. For each suggestion, create an <li> element, append it to the suggestions list, and make the list visible.

Expand
Use dark colors for code blocks
    const input = document.getElementById("geocode-input");
    const suggestionsList = document.getElementById("suggestions");
    let selectedIndex = -1;

    input.addEventListener("input", () => {
      selectedIndex = -1;
      const text = input.value;

      if (!text) return suggestionsList.style.display = "none";

      arcgisRest.suggest(text, {
        authentication,
        params: {
          maxSuggestions: 4
        }
      }).then((response) => {
        suggestionsList.innerHTML = "";
        if (!response.suggestions?.length) {
          suggestionsList.style.display = "none";
          return;
        }
        response.suggestions.forEach((s, idx) => {
          const li = document.createElement("li");
          li.textContent = s.text;

          suggestionsList.appendChild(li);
        });
        suggestionsList.style.display = "block";
      });

    });
Expand

Search for an address

When the user selects a suggestion, call the geocode method to get location coordinates.

Create a function that calls geocode using the magicKey returned by the suggest method. The magicKey helps match partial text input to a complete address. You will use this function in a later step.

Expand
Use dark colors for code blocks
    let popup = null;

    function performGeocode(magicKey) {
      arcgisRest.geocode({ magicKey, authentication }).then((response) => {
        const result = response.candidates[0];
        const lngLat = [result.location.x, result.location.y];

      });
    }
Expand

Show the location details with a popup and pan the map to the location.

Expand
Use dark colors for code blocks
    let popup = null;

    function performGeocode(magicKey) {
      arcgisRest.geocode({ magicKey, authentication }).then((response) => {
        const result = response.candidates[0];
        const lngLat = [result.location.x, result.location.y];

        popup?.remove();
        popup = new maplibregl.Popup({ focusAfterOpen: false })
          .setLngLat(lngLat)
          .setHTML(`<strong>${result.address}</strong><br />${lngLat[0].toFixed(4)}, ${lngLat[1].toFixed(4)}`)
          .addTo(map);

        const bounds = [
          [result.extent.xmin, result.extent.ymin], // [south, west]
          [result.extent.xmax, result.extent.ymax]  // [north, east]
        ];

        map.fitBounds(bounds, {
          padding: 20,
          animate: false
        });

      });
    }
Expand

Add a click handler to each suggestion item to call the performGeocode function with the suggestion's magicKey.

Expand
Use dark colors for code blocks
    const input = document.getElementById("geocode-input");
    const suggestionsList = document.getElementById("suggestions");
    let selectedIndex = -1;

    input.addEventListener("input", () => {
      selectedIndex = -1;
      const text = input.value;

      if (!text) return suggestionsList.style.display = "none";

      arcgisRest.suggest(text, {
        authentication,
        params: {
          maxSuggestions: 4
        }
      }).then((response) => {
        suggestionsList.innerHTML = "";
        if (!response.suggestions?.length) {
          suggestionsList.style.display = "none";
          return;
        }
        response.suggestions.forEach((s, idx) => {
          const li = document.createElement("li");
          li.textContent = s.text;

          li.addEventListener("click", () => {
            input.value = s.text;
            suggestionsList.style.display = "none";
            performGeocode(s.magicKey);
          });

          suggestionsList.appendChild(li);
        });
        suggestionsList.style.display = "block";
      });

    });
Expand

Improve app usability by adding hover styles, enabling keyboard navigation, and using the clear button in the input element.

Expand
Use dark colors for code blocks
    // Handle keyboard navigation in the suggestions list
    input.addEventListener("keydown", (e) => {
      const items = suggestionsList.querySelectorAll("li");

      if (e.key === "ArrowDown" && selectedIndex < items.length - 1) {
        selectedIndex++;
      } else if (e.key === "ArrowUp" && selectedIndex > 0) {
        selectedIndex--;
      } else if (e.key === "Enter" && selectedIndex >= 0) {
        items[selectedIndex].click();
      }

      items.forEach((item, i) => item.classList.toggle("selected", i === selectedIndex));
    });

    // Clear the input and remove popup when the clear button is clicked
    document.getElementById("clear-button").addEventListener("click", () => {
      input.value = "";
      popup?.remove();
    });

    // Hide suggestions if the user clicks outside the geocode container
    document.addEventListener("click", (e) => {
      if (!document.getElementById("geocode-container").contains(e.target)) {
        suggestionsList.style.display = "none";
      }
    });
Expand

Run the app

Run the app.

The map should display a geocoding input that lets you search for locations, see address suggestions, and navigate the map to a selected result.

Congratulations!

You have completed the Display a map with a basemap session how-to. The application uses a session token to access and display basemap styles. It allows you to change the basemap style, geocode to any location, and zoom in and out without restrictions. The basemap session (and session token) are valid for 12 hours and are automatically refreshed when they expire.

What's next?

Change language labels for basemap styles

Switch the language of place labels on a basemap.

Find place addresses

Search for places by category near a location.

Find a route and directions

Find a route and directions from a start and finish location.

To explore additional ArcGIS capabilities, go to Tutorials.