Autosuggest

Suggestions displayed as characters are added using a widget and the geocoding serivce

What is autosuggest?

Autosuggest, also known as autocomplete, is the process of using incomplete text to search for place names and addresses. For example, you can search for "New Y", "Dodgers S", and "Cali" to get a list of suggested place names that match.

You can use autosuggest to build applications that:

Autocomplete addresses and places as you type.
Provide a list of suggestions for incomplete address and place names.
Refine place names and addresses to improve geocoding accuracy.

How autosuggest works

You can get address and place name suggestions by making an HTTP request to the geocoding service suggest operation or by using client APIs. Specify the address or place name text, and optionally, additional parameters to refine the search.

You can provide text for a partial place name or a partial address to get search results. Typically 2-3 characters are needed to start searching.

To refine the search and improve accuracy, you can provide additional information such as the location, search extent, category, and country code.

The geocoding service parses the text and uses all of the parameters provided to return a set of suggestions. Each suggestion contains text (address or place name), isCollection (single distinct place or multiple with the same name or category), and magicKey (search identifier) properties.

URL request

https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer/suggest?<parameters>

Key parameters

Name	Description	Examples
`text`	The partial address or place name. Different formats are supported.	text=starbutext=100, main sttext=New Y

Additional parameters: Refine the search by using parameters such as location, searchExtent, category, and countryCode.

Examples

Get suggestions for a string

This example finds suggestions for the string New Y. To find the actual address and location for a suggestion, you have to pass each text and magicKey value to the geocoding service. Most APIs provide a LocatorTask to access the service.

Steps

Reference the geocoding service.
Set the text to search for.
Set the API key.

The response is a set of suggestions (max of 5) containing the text and magicKey properties. Use these properties to search for the complete address with a location.

APIs

ArcGIS JS API

Esri Leaflet

Mapbox GL JS

OpenLayers

ArcGIS REST JS

ArcGIS .NET API

ArcGIS Android API

ArcGIS iOS API

ArcGIS Java API

ArcGIS Qt API (C++)

ArcGIS Qt API (QML)

Go to tutorial

<html>
<head>
  <meta charset="utf-8">
  <meta name="viewport" content="initial-scale=1, maximum-scale=1, user-scalable=no">
  <title>ArcGIS Developer Guide: Forward geocoding</title>
      <!-- ArcGIS Mapping APIs and Location Services Developer Guide
      Learn more: https://developers.arcgis.com/documentation/mapping-apis-and-services/search/
      -->
  <style>
    html, body, #viewDiv {
      padding: 0;
      margin: 0;
      height: 100%;
      width: 100%;
    }
  </style>

  <link rel="stylesheet" href="https://js.arcgis.com/4.21/esri/themes/light/main.css">
  <script src="https://js.arcgis.com/4.21/"></script>

  <script>
    require([
      "esri/config",
      "esri/Map",
      "esri/views/MapView",
      "esri/Graphic",
      "esri/rest/locator",
    ],(esriConfig, Map, MapView, Graphic, locator)=> {
      esriConfig.apiKey = "YOUR_API_KEY";

      const map = new Map({
        basemap: "arcgis-light-gray", //Basemap layer service
      });

      const view = new MapView({
        container: "viewDiv",
        map: map,
        center: [-25, 30],
        zoom: 2,
        constraints: {
          snapToZoom: false
        }
      });

      view.popup.actions = [];

      const select = document.createElement("select", "");
      select.setAttribute("class", "esri-widget esri-select");
      select.setAttribute(
        "style",
        "width: 275px; font-family: 'Avenir Next'; font-size: 1em"
      );
      const option = document.createElement("option");
      option.innerHTML = "See suggestions for \"New Y\"...";
      select.appendChild(option);
      view.ui.add(select, "top-right");

      view.when(() => {

        locatorUrl = "https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer";

        const params = {
          text: "New Y", // Suggestion text
        };

        locator.suggestLocations(locatorUrl, params).then((response) => {
          // Show a list of the suggestions
          response.forEach((suggestion) => {
            showSuggestion(suggestion.text, suggestion.magicKey);
          });
          // When a suggestion is selected, geocode to find its location
          select.addEventListener("change", (event) => {
            const text = event.target.innerHTML;
            const magicKey = event.target.value;
            geocodeSuggestion(text, magicKey);
          });
        });

      });

      function showSuggestion(text, magicKey) {
        const option = document.createElement("option");
        option.innerHTML = text;
        option.value = magicKey;
        select.appendChild(option);
      }

      function geocodeSuggestion(suggestionText, magicKey) {
        const params = {
          SingeLine: suggestionText, // suggestion text
          address: {
            magicKey: magicKey, // suggestion magic key
          },
          outFields: ["PlaceName", "Place_addr", "LongLabel"],
        };
        // Geocode suggestion and show location
        locator.addressToLocations(locatorUrl,params).then((results) => {
          showSearchResult(results);
        });
      }

      function showSearchResult(results) {
        if (!results.length) {
          return;
        }
        const result = results[0];
        view.graphics.removeAll();
        const graphic = new Graphic({
          symbol: {
            type: "simple-marker",
            color: "#000000",
            size: "8px",
            outline: {
              color: "#ffffff",
              width: "1px",
            },
          },
          geometry: result.location,
          attributes: result.attributes,
          popupTemplate: {
            title: "{PlaceName}",
            content:
              "{LongLabel}" +
              "<br><br>" +
              result.location.longitude.toFixed(5) +
              "," +
              result.location.latitude.toFixed(5),
          },
        });
        view.graphics.add(graphic);
        view.popup.open({
          features: [graphic],
          location: result.location,
        });
        view.goTo({
          target: result.location,
          zoom: 13,
        });
      }
    });

  </script>
</head>
<body>
  <div id="viewDiv"></div>
</body>
</html>

REST API

Request

Response

curl https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer \
-d 'f=pjson' \
-d 'text=New Y' \
-d 'token=<ACCESS_TOKEN>'

Response (JSON)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
{
  "suggestions": [
    {
      "text": "New York, NY, USA",
      "magicKey": "dHA9MCNsb2M9NzUwOTc4OCNsbmc9MzMjcGw9MjcxNjU1MyNsYnM9MTQ6MjM4MTIyMzc=",
      "isCollection": false
    },
    {
      "text": "New York, USA",
      "magicKey": "dHA9MCNsb2M9NzMxOTEwOCNsbmc9MzMjcGw9MjU5OTMyMyNsYnM9MTQ6MjM4MTIyMzc=",
      "isCollection": false
    },
    {
      "text": "New York international Airport, New York, NY, USA",
      "magicKey": "dHA9MCNsb2M9OTc0ODU4OCNsbmc9MzMjcGw9MzYwNTMyOSNsYnM9MTQ6MjM4MTMzMTk=",
      "isCollection": false
    },
    {
      "text": "New York Stad, Nouvieau York, NY, USA",
      "magicKey": "dHA9MCNsb2M9OTc0ODY4OCNsbmc9MzMjcGw9MzYwNzI0MyNsYnM9MTQ6MjM4MTMwOTc=",
      "isCollection": false
    },
    {
      "text": "New York Mills, NY, USA",
      "magicKey": "dHA9MCNsb2M9NzUwMTA0MyNsbmc9MzMjcGw9MjcxMzU0MyNsYnM9MTQ6MjM4MTI4NDA=",
      "isCollection": false
    }
  ]
}

Tutorials

Search for an address

Convert an address or place to a location with the Geocoding service.

Reverse geocode

Get an address, business, or place from coordinates with the Geocoding service.

Find places

Find an address, business, or place with the Geocoding service.

Services

Geocoding service

Search for addresses, businesses, and places around the world.

API support

	Geocoding	Reverse Geocoding	Batch Geocoding	Place/POI Search	Autosuggest
ArcGIS API for JavaScript
ArcGIS API for Android
ArcGIS API for iOS
ArcGIS API for Java
ArcGIS API for .NET
ArcGIS API for Qt
ArcGIS API for Python
Esri Leaflet			¹
MapBox GL JS	¹	¹	¹	¹	¹
OpenLayers	¹	¹	¹	¹	¹
ArcGIS REST JS

Full supportPartial supportNo support

1. Access via ArcGIS REST JS

Tools

Developer dashboard

Manage API keys, service usage, and data with the ArcGIS Developers website.

ArcGIS Online

Create, manage, and share content and data with cloud-based GIS tools.

Map Viewer

Create, explore, and share web maps for 2D applications.

Scene Viewer

Create, explore, and share web scenes for 3D applications.

ArcGIS Pro

Explore, visualize, and analyze both 2D and 3D data with desktop GIS tools.

PreviousPlace search NextReverse geocoding

DocumentationMapping APIs and services

Autosuggest

Was this page helpful?

Was this page helpful?