Search for an address

Learn how to find an address or place with a search bar and the Geocoding service.

Geocoding is the process of converting address or place text into a location. The geocoding service can search for an address or a place and perform reverse geocoding.

In this tutorial, you use a search bar in the user interface to access the geocoding service and search for addresses and places.

To learn how to use the geocoding service to reverse geocode, visit the Reverse geocode tutorial.

Prerequisites

Before starting this tutorial:

You need an ArcGIS Location Platform or ArcGIS Online account.
Confirm that your system meets the minimum system requirements.
An IDE for Java.

Steps

Get an access token

You need an access token to use the location services used in this tutorial.

Go to the Create an API key tutorial to obtain an access token using your ArcGIS Location Platform or ArcGIS Online account.
Ensure that the following privileges are enabled: Location services > Basemaps > Basemap styles service and Location services > Geocoding.
Copy the access token as it will be used in the next step.

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

Open a Java project with Gradle

To start this tutorial, complete the Display a map tutorial, or download and unzip the Display a map solution into a new folder.
Open the build.gradle file as a project in IntelliJ IDEA.
In IntelliJ IDEA's Project tool window, open src/main/java/com.example.app and double-click App.
In the start() method, set the API key property on the AGSArcGISRuntimeEnvironment with your access token. Replace YOUR_ACCESS_TOKEN with your copied access token. Be sure to surround your access token with double quotes as it is a string.
App.java
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
    ArcGISRuntimeEnvironment.setApiKey("YOUR_ACCESS_TOKEN");
```
Warning
The access token is stored directly in the code as a convenience for this tutorial. Storing access tokens in the source code is not best practice.

Add import statements and variable declarations

Add import statements and variable declarations to reference the packages and classes required for this tutorial.

In the IntelliJ IDEA > Project tool window, open src/main/java/com.example.app and click App.

Add the following imports above the existing imports:

App.java
Use dark colors for code blocks
16
16
16
16
16
16
16
16
16
16
16
16
16
16
16
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
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
43
Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.import java.util.List;
import java.util.concurrent.ExecutionException;

import com.esri.arcgisruntime.mapping.Viewpoint;
import javafx.geometry.Insets;
import javafx.geometry.Pos;
import javafx.scene.control.Alert;
import javafx.scene.control.TextField;

import com.esri.arcgisruntime.concurrent.ListenableFuture;
import com.esri.arcgisruntime.mapping.view.Graphic;
import com.esri.arcgisruntime.mapping.view.GraphicsOverlay;
import com.esri.arcgisruntime.symbology.SimpleMarkerSymbol;
import com.esri.arcgisruntime.symbology.TextSymbol;
import com.esri.arcgisruntime.tasks.geocode.GeocodeParameters;
import com.esri.arcgisruntime.tasks.geocode.GeocodeResult;
import com.esri.arcgisruntime.tasks.geocode.LocatorTask;

import com.esri.arcgisruntime.ArcGISRuntimeEnvironment;
import com.esri.arcgisruntime.mapping.ArcGISMap;
import com.esri.arcgisruntime.mapping.BasemapStyle;
import com.esri.arcgisruntime.mapping.view.MapView;

import javafx.application.Application;
import javafx.scene.Scene;
import javafx.scene.layout.StackPane;
import javafx.stage.Stage;

Within the App class, add the following member variables to easily reference them from other parts of the application:

App.java
Use dark colors for code blocks
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
44
45
46
47
48
49
50
51
52
53
53
53
53
53
53
53
53
53
53
53
53
53
53
53
53
53
53
53
53
53
53
53
53
53
53
53
53
52
51
50
49
48
47
46
45
44
43
42
41
40
39
38
37
36
35
34
33
32
31
30
29
28
28
28
27
26
25
24
23
22
21
20
19
18
17
16
15
14
13
12
11
10
9
8
7
6
5
4
3
2
1
0
-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
-25
-25
-25
-25
-25
-25
-25
-25
-25
-25
-25
Add line.Add line.Add line.Add line.Add line.public class App extends Application {

  private MapView mapView;

  private GeocodeParameters geocodeParameters;
  private GraphicsOverlay graphicsOverlay;
  private LocatorTask locatorTask;

  private TextField searchBox;

Add a graphics overlay

A graphics overlay is a container for graphics. A graphic will be added later in this tutorial as a visual means to display the search result on the map.

In the start() method, create a new GraphicsOverlay and add it to the mapView.

App.java
Expand
Use dark colors for code blocks
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
80
81
82
83
84
85
86
87
88
89
89
88
87
86
85
84
83
82
81
80
79
78
77
76
75
74
74
74
73
72
71
70
69
68
67
66
65
64
63
62
61
60
59
58
57
56
55
54
53
52
51
50
49
48
47
46
45
44
43
42
41
40
39
38
37
36
35
34
33
32
31
30
29
28
27
26
25
24
23
22
21
21
21
21
21
21
21
21
21
21
21
21
Add line.Add line.Add line.Add line.    ArcGISMap map = new ArcGISMap(BasemapStyle.ARCGIS_TOPOGRAPHIC);
    // set the map on the map view
    mapView.setMap(map);
    mapView.setViewpoint(new Viewpoint(34.02700, -118.80543, 144447.638572));

    // create a graphics overlay and add it to the map view
    graphicsOverlay = new GraphicsOverlay();

    mapView.getGraphicsOverlays().add(graphicsOverlay);
Expand

Add a UI for user input

To search an address using the application, add a UI element to prompt the user for text input. The text input will be used as the geocode search text in a later step.

Create a new private method named setupTextField().

Within the method body, create a JavaFX TextField, assign it to the searchBox member variable, and set its width and prompt text.

App.java
Expand
Use dark colors for code blocks
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
89
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
91
92
93
94
95
96
97
97
96
95
94
93
92
91
90
89
88
87
86
85
84
83
82
81
80
79
78
77
76
75
74
73
72
71
70
69
68
67
66
65
64
63
62
61
60
59
58
57
56
55
54
53
52
51
50
50
50
50
50
50
50
50
50
50
50
50
Add line.Add line.Add line.Add line.Add line.    mapView.getGraphicsOverlays().add(graphicsOverlay);

  }

  private void setupTextField() {
    searchBox = new TextField();
    searchBox.setMaxWidth(400);
    searchBox.setPromptText("Search for an address");
  }
Expand

Call the setupTextField() method in the start() method.

App.java
Expand
Use dark colors for code blocks
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
88
89
90
91
91
90
89
88
87
86
85
84
83
82
81
80
79
78
78
78
78
78
78
78
78
78
77
76
75
74
73
72
71
70
69
68
67
66
65
64
63
62
61
60
59
58
57
56
55
54
53
52
51
50
49
48
47
46
45
44
43
42
41
40
39
38
37
36
35
34
33
32
31
31
31
31
31
31
31
31
31
31
31
31
Add line.    mapView.getGraphicsOverlays().add(graphicsOverlay);

    setupTextField();
Expand

Add the searchBox to the top left of the map, setting its alignment and margins as shown:

App.java
Expand
Use dark colors for code blocks
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
91
92
92
92
92
92
92
92
92
92
92
93
94
95
96
97
97
97
97
97
97
97
97
96
95
94
93
92
91
90
89
88
87
86
85
84
83
82
81
80
79
78
77
76
75
74
73
72
71
70
69
68
67
66
65
64
63
62
61
60
59
58
57
56
55
54
53
52
51
50
50
50
50
50
50
50
50
50
50
50
50
Add line.Add line.Add line.    setupTextField();

    stackPane.getChildren().add(searchBox);
    StackPane.setAlignment(searchBox, Pos.TOP_LEFT);
    StackPane.setMargin(searchBox, new Insets(10, 0, 0, 10));

  }
Expand

Create a locator task with geocode parameters

Geocoding is implemented with a locator, typically created by referencing a service such as the Geocoding service or, for offline geocoding, by referencing locator data contained in a mobile package. Geocoding parameters can be used to fine-tune the results, such as setting the maximum number of results or requesting additional attributes in the results.

Create a new private method named createLocatorTaskAndDefaultParameters().
Within the method body, create a new LocatorTask based on the Geocoding service, and assign it to the locatorTask member variable.

A locator task is used to convert an address to a point (geocode) or vice-versa (reverse geocode). An address includes any type of information that distinguishes a place. A locator involves finding matching locations for a given address. Reverse-geocoding is the opposite and finds the closest address for a given location.
Create new GeocodeParameters, and assign it to the geocodeParameters member variable. Specify the geocode's attributes as follows:
- Specify which attributes to return with getResultAttributeNames().add(). * is used to return all attributes.
- Set the maximum number of results to be returned with setMaxResults(). In this tutorial, only return the best match by passing in 1. Results are ordered by score, so returning only the first result will return the highest scoring result.
- Set the spatial reference with setOutputSpatialReference(). By default the output spatial reference is determined by the geocode service. For optimal performance when displaying the geocode result, ensure the returned coordinates match those of the map view by providing mapView.getSpatialReference() as a parameter.
When geocoding an address, you can optionally provide GeocodeParameters to control certain aspects of the geocoding operation, and specify the kinds of results to return from the locator task. Learn more about these parameters in the API documentation.
App.java
Expand
Use dark colors for code blocks
107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 107 106 105 104 103 102 101 100 99 98 98 98 98 98 98 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 112 111 110 109 108 107 106 105 104 103 102 101 100 99 98 97 96 95 94 93 92 91 90 89 88 87 86 85 84 83 82 81 80 79 78 77 76 75 74 74 74 74 74 74 74 74 74 74 74 74
Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.
```
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
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
  private void setupTextField() {
    searchBox = new TextField();
    searchBox.setMaxWidth(400);
    searchBox.setPromptText("Search for an address");
  }

  private void createLocatorTaskAndDefaultParameters() {
    locatorTask = new LocatorTask("https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer");

    geocodeParameters = new GeocodeParameters();
    geocodeParameters.getResultAttributeNames().add("*");
    geocodeParameters.setMaxResults(1);
    geocodeParameters.setOutputSpatialReference(mapView.getSpatialReference());
  }
```
Expand

Call the createLocatorTaskAndDefaultParameters() method in the start() method.

App.java
Expand
Use dark colors for code blocks
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
90
91
92
93
93
92
91
90
89
88
87
86
86
86
86
86
86
86
86
86
86
86
86
86
85
84
83
82
81
80
79
78
77
76
75
74
73
72
71
70
69
68
67
66
65
64
63
62
61
60
59
58
57
56
55
54
53
52
51
50
49
48
47
46
45
44
43
42
41
40
39
39
39
39
39
39
39
39
39
39
39
39
Add line.    setupTextField();

    createLocatorTaskAndDefaultParameters();
Expand

Get the geocode results with a geocode operation

An asynchronous geocode operation is required to find and return the location candidates for a given address and geocode parameters.

Create a new private method named performGeocode() that takes a String parameter for the address.

To find the location for a given address, call the geocodeAsync method on the locatorTask, providing the address string and geocodeParameters as parameters, and store the result in a local variable named geocodeResults. The result is an unmodifiable list of GeocodeResult objects. In this tutorial, only one result will be returned, as the maximum results parameter was set to 1. Get the location result by calling an addDoneListener() on the geocodeResults. The result will be displayed visually in the next step.

App.java
Expand
Use dark colors for code blocks
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
113
112
111
110
109
108
107
106
106
106
106
106
106
106
106
106
106
106
106
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
124
124
125
126
127
128
129
130
131
132
133
133
132
131
130
129
128
127
126
125
124
123
122
121
120
119
118
117
116
116
116
116
116
116
116
116
116
116
116
116
Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.  private void createLocatorTaskAndDefaultParameters() {
    locatorTask = new LocatorTask("https://geocode-api.arcgis.com/arcgis/rest/services/World/GeocodeServer");

    geocodeParameters = new GeocodeParameters();
    geocodeParameters.getResultAttributeNames().add("*");
    geocodeParameters.setMaxResults(1);
    geocodeParameters.setOutputSpatialReference(mapView.getSpatialReference());
  }

  private void performGeocode(String address) {
    ListenableFuture<List<GeocodeResult>> geocodeResults = locatorTask.geocodeAsync(address, geocodeParameters);

    geocodeResults.addDoneListener(() -> {
      try {
        List<GeocodeResult> geocodes = geocodeResults.get();
        if (geocodes.size() > 0) {
          GeocodeResult result = geocodes.get(0);

        } else {
          new Alert(Alert.AlertType.INFORMATION, "No results found.").show();
        }
      } catch (InterruptedException | ExecutionException e) {
        new Alert(Alert.AlertType.ERROR, "Error getting result.").show();
        e.printStackTrace();
      }
    });
  }
Expand

Display the result

The result obtained from the geocode operation can be displayed by adding a graphic to the map view's graphics overlay.

Create a new private method taking a GeocodeResult (the result to be displayed on the map) as a parameter, and name it displayResult().

Within the method body, create and style two Graphics and add them to the graphicsOverlay. Use the geocodeResult's label and display location to add one graphic showing the geocode result's label text (the address), and another showing the geocode result's location.

App.java
Expand
Use dark colors for code blocks
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
133
132
131
130
129
128
127
126
126
126
126
126
126
126
126
126
126
126
126
126
126
126
126
126
126
126
126
126
126
126
126
126
126
126
126
126
126
126
125
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
150
150
150
150
150
150
150
150
150
150
150
150
Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.Add line.        } else {
          new Alert(Alert.AlertType.INFORMATION, "No results found.").show();
        }
      } catch (InterruptedException | ExecutionException e) {
        new Alert(Alert.AlertType.ERROR, "Error getting result.").show();
        e.printStackTrace();
      }
    });
  }

  private void displayResult(GeocodeResult geocodeResult) {
    graphicsOverlay.getGraphics().clear(); // clears the overlay of any previous result

    // create a graphic to display the address text
    String label = geocodeResult.getLabel();
    TextSymbol textSymbol = new TextSymbol(18, label, 0xFF000000, TextSymbol.HorizontalAlignment.CENTER, TextSymbol.VerticalAlignment.BOTTOM);
    Graphic textGraphic = new Graphic(geocodeResult.getDisplayLocation(), textSymbol);
    graphicsOverlay.getGraphics().add(textGraphic);

    // create a graphic to display the location as a red square
    SimpleMarkerSymbol markerSymbol = new SimpleMarkerSymbol(SimpleMarkerSymbol.Style.SQUARE, 0xFFFF0000, 12.0f);
    Graphic markerGraphic = new Graphic(geocodeResult.getDisplayLocation(), geocodeResult.getAttributes(), markerSymbol);
    graphicsOverlay.getGraphics().add(markerGraphic);

    mapView.setViewpointCenterAsync(geocodeResult.getDisplayLocation());
  }
Expand

In the performGeocode() method, in the lambda expression body, call the displayResult() method, passing in result as the parameter. This will display the result of the geocode operation on the map.

App.java
Expand
Use dark colors for code blocks
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
124
123
122
121
120
119
118
118
118
118
118
118
118
118
118
118
118
118
118
118
118
118
118
118
118
118
118
118
118
118
118
119
120
121
122
123
124
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
125
Add line.    geocodeResults.addDoneListener(() -> {
      try {
        List<GeocodeResult> geocodes = geocodeResults.get();
        if (geocodes.size() > 0) {
          GeocodeResult result = geocodes.get(0);

          displayResult(result);
Expand

In the start() method, set an action on the searchBox to get the input text. Get the text from the search box and call performGeocode(), passing in the text as the parameter.

App.java
Expand
Use dark colors for code blocks
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
92
93
94
95
96
97
98
99
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
100
Add line.Add line.Add line.Add line.Add line.Add line.    createLocatorTaskAndDefaultParameters();

    searchBox.setOnAction(event -> {
      String address = searchBox.getText();
      if (!address.isBlank()) {
        performGeocode(address);
      }
    });
Expand

Run the app. Ensure to run the app as a Gradle task and not as an application in your IDE. In the Gradle tool window, under Tasks > application, click run.

You should see a search box on the top left of the map. Search for an address by entering an address and press Return on the keyboard. The result of the search should display on the map as a red square.

What's next?

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