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.
-
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 theAGS
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.ArcGIS Runtime Environment App.javaUse dark colors for code blocks ArcGISRuntimeEnvironment.setApiKey("YOUR_ACCESS_TOKEN");
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.javaUse dark colors for code blocks 34 35 36 37 38 39 40 41 42 43Add 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.javaUse dark colors for code blocks 45 46 47 48Add 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 newGraphics
and add it to theOverlay map
.View App.javaUse dark colors for code blocks 81 82 83 84 85Add 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);
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
setup
.Text Field() -
Within the method body, create a JavaFX
Text
, assign it to theField search
member variable, and set its width and prompt text.Box App.javaUse dark colors for code blocks 89 90 91 92Add 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"); }
-
Call the
setup
method in theText Field() start()
method.App.javaUse dark colors for code blocks 89 90Add line. mapView.getGraphicsOverlays().add(graphicsOverlay); setupTextField();
-
Add the
search
to the top left of the map, setting its alignment and margins as shown:Box App.javaUse dark colors for code blocks 91 92 96 97Add 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)); }
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
create
.Locator Task And Default Parameters() -
Within the method body, create a new
Locator
based on the Geocoding service, and assign it to theTask locator
member variable.Task 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
Geocode
, and assign it to theParameters geocode
member variable. Specify the geocode's attributes as follows:Parameters - Specify which attributes to return with
get
.Result Attribute Names().add() *
is used to return all attributes. - Set the maximum number of results to be returned with
set
. In this tutorial, only return the best match by passing inMax Results() 1
. Results are ordered byscore
, so returning only the first result will return the highest scoring result. - Set the spatial reference with
set
. 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 providingOutput Spatial Reference() map
as a parameter.View.get Spatial Reference()
When geocoding an address, you can optionally provide
Geocode
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.Parameters App.javaUse dark colors for code blocks 99 100 101 102 103 104Add line. Add line. Add line. Add line. Add line. Add line. Add line. Add line. 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()); }
- Specify which attributes to return with
-
Call the
create
method in theLocator Task And Default Parameters() start()
method.App.javaUse dark colors for code blocks 91 92Add line. setupTextField(); createLocatorTaskAndDefaultParameters();
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
perform
that takes aGeocode() String
parameter for the address. -
To find the location for a given address, call the
geocode
method on theAsync locator
, providing theTask address
string andgeocode
as parameters, and store the result in a local variable namedParameters geocode
. The result is an unmodifiable list ofResults Geocode
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 anResult add
on theDone Listener() geocode
. The result will be displayed visually in the next step.Results App.javaUse dark colors for code blocks 107 108 109 110 111 112 113 114 115Add 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(); } }); }
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
Geocode
(the result to be displayed on the map) as a parameter, and name itResult display
.Result() -
Within the method body, create and style two
Graphic
s and add them to thegraphics
. Use theOverlay geocode
'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.Result App.javaUse dark colors for code blocks 125 126 127 128 129 130 131 132 133 134Add 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()); }
-
In the
perform
method, in the lambda expression body, call theGeocode() display
method, passing inResult() result
as the parameter. This will display the result of the geocode operation on the map.App.javaUse dark colors for code blocks 119 120 121 122 123 124Add line. geocodeResults.addDoneListener(() -> { try { List<GeocodeResult> geocodes = geocodeResults.get(); if (geocodes.size() > 0) { GeocodeResult result = geocodes.get(0); displayResult(result);
-
In the
start()
method, set an action on thesearch
to get the input text. Get the text from the search box and callBox perform
, passing in the text as the parameter.Geocode() App.javaUse dark colors for code blocks 93 94Add line. Add line. Add line. Add line. Add line. Add line. createLocatorTaskAndDefaultParameters(); searchBox.setOnAction(event -> { String address = searchBox.getText(); if (!address.isBlank()) { performGeocode(address); } });
-
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: