Find places

Learn how to search for businesses, POIs, and geographic locations with the geocoding service.

Place finding is the process of searching for a place name or POI to find its address and location. You can use the Geocoding service to find places such as coffee shops, gas stations, or restaurants for any geographic location around the world. You can search for places by name or by using categories. You can search near a location or you can search globally.

In this tutorial, you will use a locator to access the Geocoding service and find places by place category. Pop-ups are used to display the place name and address.

Prerequisites

Steps

Create a new pen

1. To get started, either complete the Display a map tutorial or use this pen.

Get an access token

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

1. Go to the Create an API key tutorial and create an API key with the following privilege(s):
   
   • Privileges
     • Location services > Basemaps
     • Location services > Geocoding
2. In CodePen, set esriConfig.apiKey to your access token.
   Use dark colors for code blocks

   1
   2
   3
   4
   5
   6
   7
   8
   9
     var esriConfig = {
       apiKey: "YOUR_ACCESS_TOKEN",
     };
   

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

Update the map

A streets basemap layer is typically used in geocoding applications. Update the basemap attribute to use the arcgis/navigation basemap layer and change the position of the map to center on Tromso.

1. Update the basemap attribute from arcgis/topographic to arcgis/navigation and the center to 18.9553,69.6492.

   Expand

   Use dark colors for code blocks

   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
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
       <arcgis-map basemap="arcgis/navigation" center="18.9553,69.6492" zoom="13">
   
         <arcgis-zoom slot="top-left"></arcgis-zoom>
   
       </arcgis-map>
   

   Expand

Create a place category selector

You filter place search results by providing a location and category. Places can be filtered by categories such as coffee shop, gas station, and hotels. Use a Calcite Select component to provide a list of several categories from which to choose.

1. Inside a Calcite Block component, add a Calcite Select component with an id of places-select and a Label of Choose a place type.

   Expand

   Use dark colors for code blocks

   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
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
       <arcgis-map basemap="arcgis/navigation" center="18.9553,69.6492" zoom="13">
   
         <arcgis-zoom slot="top-left"></arcgis-zoom>
   
         <calcite-block expanded slot="top-right">
           <calcite-label id="places-select-label">
             Choose a place type
             <calcite-select id="places-select">
   
             </calcite-select>
           </calcite-label>
         </calcite-block>
   
       </arcgis-map>
   

   Expand

2. Create an option component for each category and add it to the Select component.

   Expand

   Use dark colors for code blocks

   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
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
       <arcgis-map basemap="arcgis/navigation" center="18.9553,69.6492" zoom="13">
   
         <arcgis-zoom slot="top-left"></arcgis-zoom>
   
         <calcite-block expanded slot="top-right">
           <calcite-label id="places-select-label">
             Choose a place type
             <calcite-select id="places-select">
   
               <calcite-option value="Parks and Outdoors">Parks and Outdoors</calcite-option>
               <calcite-option value="Coffee shop">Coffee shop</calcite-option>
               <calcite-option value="Gas station">Gas station</calcite-option>
               <calcite-option value="Food">Food</calcite-option>
               <calcite-option value="Hotel">Hotel</calcite-option>
   
             </calcite-select>
           </calcite-label>
         </calcite-block>
   
       </arcgis-map>
   

   Expand

Add a script

1. Add a script tag with the type attribute set to module, to the bottom of the body.

   Expand

   Use dark colors for code blocks

   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
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
     <body>
   
       <arcgis-map basemap="arcgis/navigation" center="18.9553,69.6492" zoom="13">
   
         <arcgis-zoom slot="top-left"></arcgis-zoom>
   
         <calcite-block expanded slot="top-right">
           <calcite-label id="places-select-label">
             Choose a place type
             <calcite-select id="places-select">
   
               <calcite-option value="Parks and Outdoors">Parks and Outdoors</calcite-option>
               <calcite-option value="Coffee shop">Coffee shop</calcite-option>
               <calcite-option value="Gas station">Gas station</calcite-option>
               <calcite-option value="Food">Food</calcite-option>
               <calcite-option value="Hotel">Hotel</calcite-option>
   
             </calcite-select>
           </calcite-label>
         </calcite-block>
   
       </arcgis-map>
   
       <script type="module">
   
       </script>
   
     </body>
   

   Expand

2. Using $arcgis.import, add the Graphic and locator modules.

   More info

   The ArcGIS Maps SDK for JavaScript is available via CDN and npm, but this tutorial is based on CDN. The $arcgis.import global function accepts a module path or array of module paths, and returns a promise that resolves with the requested modules. This function can only be used when working with the CDN; otherwise, use the standard import syntax. To learn more about the SDK's different modules, visit the References page.

   Expand

   Use dark colors for code blocks

   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
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
       <script type="module">
   
         const [Graphic, locator] = await $arcgis.import([
           "@arcgis/core/Graphic",
           "@arcgis/core/rest/locator",
         ]);
   
       </script>
   

   Expand

Define variables for the components

Define variables for the components you will use in the app. You will use these variables to access the components and their properties.

1. Define variables for the map and placesSelect components.

   Expand

   Use dark colors for code blocks

   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
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
       <script type="module">
   
         const [Graphic, locator] = await $arcgis.import([
           "@arcgis/core/Graphic",
           "@arcgis/core/rest/locator",
         ]);
   
         const placesSelectElement = document.querySelector("#places-select");
         const viewElement = document.querySelector("arcgis-map");
   
       </script>
   

   Expand

Define the service url

You can use a locator to access the Geocoding service.

1. Define a variable, locatorUrl, to the URL for the Geocoding service.
   Expand

   Use dark colors for code blocks

   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
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
       <script type="module">
   
         const [Graphic, locator] = await $arcgis.import([
           "@arcgis/core/Graphic",
           "@arcgis/core/rest/locator",
         ]);
   
         const placesSelectElement = document.querySelector("#places-select");
         const viewElement = document.querySelector("arcgis-map");
   
         const locatorUrl = "http://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer";
   
       </script>
   

   Expand

Search for places

To find places, use the locator addressToLocations function. Performing a local search based on a category requires a location from which to search and a category name. The function sends a request to the Geocoding service and the service returns place candidates with a name, address and location information. Use the function to perform a search and add the results to the map as graphics.

1. Create a findPlaces function and call addressToLocations. Set the location, categories and outFields properties.

   Expand

   Use dark colors for code blocks

   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
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
       <script type="module">
   
         const [Graphic, locator] = await $arcgis.import([
           "@arcgis/core/Graphic",
           "@arcgis/core/rest/locator",
         ]);
   
         const placesSelectElement = document.querySelector("#places-select");
         const viewElement = document.querySelector("arcgis-map");
   
         const locatorUrl = "http://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer";
   
         async function findPlaces(category, point) {
           const results = await locator.addressToLocations(locatorUrl, {
             location: point,
             categories: [category],
             maxLocations: 25,
             outFields: ["Place_addr", "PlaceName"],
           });
   
         }
   
       </script>
   

   Expand

2. Clear the view of existing pop-ups and graphics.

   Expand

   Use dark colors for code blocks

   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
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
         async function findPlaces(category, point) {
           const results = await locator.addressToLocations(locatorUrl, {
             location: point,
             categories: [category],
             maxLocations: 25,
             outFields: ["Place_addr", "PlaceName"],
           });
   
           viewElement.closePopup();
           viewElement.graphics.removeAll();
   
         }
   

   Expand

3. Create a Graphic for each result returned. Set the attributes, geometry, symbol and popupTemplate properties for each. Add each graphic to the viewElement.

   Expand

   Use dark colors for code blocks

   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
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
         async function findPlaces(category, point) {
           const results = await locator.addressToLocations(locatorUrl, {
             location: point,
             categories: [category],
             maxLocations: 25,
             outFields: ["Place_addr", "PlaceName"],
           });
   
           viewElement.closePopup();
           viewElement.graphics.removeAll();
   
           results.forEach((result) => {
             viewElement.graphics.add(
               new Graphic({
                 attributes: result.attributes,
                 geometry: result.location,
                 symbol: {
                   type: "simple-marker",
                   color: "#000000",
                   size: "12px",
                   outline: {
                     color: "#ffffff",
                     width: "2px",
                   },
                 },
                 popupTemplate: {
                   title: "{PlaceName}",
                   content: "{Place_addr}",
                 },
               }),
             );
           });
   
         }
   

   Expand

4. Call the findPlaces function when the Map loads and each time the Map changes and becomes stationary by listening to the arcgisViewChange event.

   Expand

   Use dark colors for code blocks

   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
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
         viewElement.addEventListener("arcgisViewChange", () => {
           if (viewElement.stationary) {
             findPlaces(placesSelectElement.value, viewElement.center);
           }
         });
   
   

   Expand

5. Places for parks should be displayed on the map. By dragging the map, you will see new places populate the view.

Add a handler to select a category

Use an event handler to call the findPlaces function when the category is changed.

1. Add a calciteSelectChange event listener to listen for category changes.
   Expand

   Use dark colors for code blocks

   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
   30
   31
   32
   33
   34
   35
   36
   37
   38
   39
   40
   41
   42
   43
   44
   45
   46
   47
   48
   49
   50
   51
   52
   53
   54
   55
   56
   57
   58
   59
   60
   61
   62
   63
   64
   65
   66
   67
   68
   69
   70
   71
   72
   73
   74
   75
   76
   77
   78
   79
   80
   81
   82
   83
   84
   85
   86
   87
   88
   89
   90
   91
   92
   93
   94
   95
   96
   97
   98
   99
   100
   101
   102
   103
   104
   105
   106
   107
   108
   109
   110
   111
   112
   113
   114
   115
   116
   117
         viewElement.addEventListener("arcgisViewChange", () => {
           if (viewElement.stationary) {
             findPlaces(placesSelectElement.value, viewElement.center);
           }
         });
   
         placesSelectElement.addEventListener("calciteSelectChange", () => {
           findPlaces(placesSelectElement.value, viewElement.center);
         });
   

   Expand

Run the app

In CodePen, run your code to display the map.

When you select a category, you should see places displayed in the center of the map for the category you selected. The search occurs when the map loads and when the map view position changes by zooming or panning. You can also click on the graphics to display pop-ups with the name and address information for each place.

What's next?

Learn how to use additional API features and ArcGIS services in these tutorials:

• Search for an address
• Find a route and directions