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.

Prerequisites

The following are required for this tutorial:

An ArcGIS account to access your API keys. If you don't have an account, sign up for free.
Confirm that your system meets the minimum system requirements.
An IDE for Java.

Steps

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.

If you downloaded the solution project, set your API key.

An API Key enables access to services, web maps, and web scenes hosted in ArcGIS Online.

Go to your developer dashboard to get your API key. For these tutorials, use your default API key. It is scoped to include all of the services demonstrated in the tutorials.
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 ArcGISRuntimeEnvironment with your API key. Replace YOUR_API_KEY with your actual API Key. Be sure to surround your API Key with quotes, because the parameter passed to setApiKey is a string.

App.java
Use dark colors for code blocks
  @Override
  public void start(Stage stage) {
    // set the title and size of the stage and show it
    stage.setTitle("Display a map tutorial");
    stage.setWidth(800);
    stage.setHeight(700);
    stage.show();

    // create a JavaFX scene with a stack pane as the root node, and add it to the scene
    StackPane stackPane = new StackPane();
    Scene scene = new Scene(stackPane);
    stage.setScene(scene);

    // Note: it is not best practice to store API keys in source code.
    // The API key is referenced here for the convenience of this tutorial.
    String yourApiKey = "YOUR_API_KEY";
    ArcGISRuntimeEnvironment.setApiKey(yourApiKey);

Add import statements and variable declarations

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

In IntelliJ IDEA's Project tool window, open src/main/java/com.example.app and double-click App.

Add the following imports above the existing imports:

App.java
Use dark colors for code blocks
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 javafx.geometry.Insets;
import javafx.geometry.Pos;
import javafx.scene.paint.Color;
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.Viewpoint;
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
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
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
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
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
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 with the Geocoding service URL, 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 by calling the .add() method on the GeocodeParameters.getResultAttributeNames(). * is used to return all attributes.
- Set the maximum number of results to be returned with GeocodeParameters.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 GeocodeParameters.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.
App.java
Expand
Use dark colors for code blocks
111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 111 110 109 108 107 106 105 104 103 102 102 102 102 102 102 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 116 115 114 113 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 78 78 78 78 78 78 78 78 78 78 78
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 172 173 174 175 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
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 LocatorTask.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 immutable 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 ListenableFuture.addDoneListener() on the geocodeResults. The result will be displayed visually in the next step.

App.java
Expand
Use dark colors for code blocks
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 Graphic objects 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
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, Color.BLACK, 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, Color.RED, 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
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
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, double-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:

ArcGIS Maps SDK for Java

Search for an address

Was this page helpful?