Hide Table of Contents
esri/dijit/util
esri/layer/pixelFilters
esri/process
esri/workers
Class: Geocoder

require(["esri/dijit/Geocoder"], function(Geocoder) { /* code goes here */ });

Description

(Added at v3.3)
The Geocoder widget was deprecated in version 3.13 and replaced by the Search widget. Apps created with version 3.13 or later should use the Search widget instead of the Geocoder widget.

Add a geographic search box to an application. The widget defaults to the ArcGIS Online World Geocoding Service but can be customized to use one or more ArcGIS Server geocoding services.

Note: When using a Map with a SpatialReference other than Web Mercator or Geographic, be sure to set a default GeometryService. This will ensure that the user's position is returned in the same SpatialReference as the Map.

require(["esri/config"], function(esriConfig) {
  esriConfig.defaults.geometryService = "http://www.example.com/arcgis/rest/services/Utilities/Geometry/GeometryServer";
});

Samples

Search for samples that use this class.

Constructors

NameSummary
new Geocoder(params, srcNodeRef)Create a new Geocoder widget using the given DOM node.

CSS

esri/dijit/Geocoder | Download source

NameDescription
esriGeocoderRepresents an instance of the node where the Geocode widget is rendered. The widget comes with two out-of-the-box themes simple and arcgisGeocoder.
.simpleGeocoder .esriGeocoder{
    border: 1px solid #708090;
}
esriGeocoderActiveThe class applied to the widget node when the results menu is active.
.simpleGeocoder .esriGeocoderActive, .simpleGeocoder .esriGeocoderMenuActive {
    border-bottom: 0 none;
    border-radius: 5px 5px 0 0;
}
esriGeocoderClearFloatStyle's that are used to clear floats in the Geocoder widget.
esriGeocoderContainerThe containing class for the geocoder node.
esriGeocoderHasValueAdded to the DOM node when the geocoder has a value.
esriGeocoderIconRepresents an icon node.
.arcgisGeocoder .esriGeocoderIcon {
 display: block;
 float: right; 
 height: 16px;
 margin: 2px 5px 2px 0;
 outline: 0 none;
 overflow: hidden;
 width: 16px;
}
esriGeocoderLoadingDefines the loading spinner that displays in the textbox.
.arcgisGeocoder .esriGeocoderLoading .esriGeocoderReset {
    background: url("../dijit/images/loading.gif") no-repeat scroll center center transparent;
}
esriGeocoderMenuThe geocoder menu.
.arcgisGeocoder .esriGeocoderMenu {
    background: none repeat scroll 0 0 #FFFFFF;
    border-right: 1px solid #8B8B8B;
    border-width: 0 1px 1px;
}
esriGeocoderMenuActiveDisplayed when the geocoder menu is shown.
.arcgisGeocoder .esriGeocoderActive, .arcgisGeocoder .esriGeocoderMenuActive {
    border-bottom: 0 none;
}
esriGeocoderMenuArrowThe button to display the geocoder menu inside the textbox container node.
.arcgisGeocoder .esriGeocoder .esriGeocoderMenuArrow {
    background: url("../dijit/images/arcgisGeocoder.png") no-repeat scroll -32px 0 transparent;
    cursor: pointer;
}
esriGeocoderMenuCloseThe close button on the geocoder menu.
.arcgisGeocoder .esriGeocoderMenu .esriGeocoderMenuClose {
    background: url("../dijit/images/arcgisGeocoder.png") no-repeat scroll -64px 0 transparent;
}
esriGeocoderMenuHeaderThe geocoder menu header.
.arcgisGeocoder .esriGeocoderMenu .esriGeocoderMenuHeader {
    border-bottom: 1px solid #8B8B8B;
    color: #000000;
}
esriGeocoderMultipleRepresents the styles for multiple geocoders.
.simpleGeocoder .esriGeocoderMultiple input {
  width: 146px;
}
esriGeocoderResetThe reset button
.arcgisGeocoder .esriGeocoderHasValue .esriGeocoderReset {
    background: url("../dijit/images/arcgisGeocoder.png") no-repeat scroll -48px 0 transparent;
}
esriGeocoderResultAn item in the result menu.
.arcgisGeocoder .esriGeocoderResult {
    cursor: pointer;
    display: block;
    padding: 5px;
    text-overflow: ellipsis;
    white-space: nowrap;
}
esriGeocoderResultEvenAn even item in the results menu.
.simpleGeocoder .esriGeocoderResult:hover, .simpleGeocoder .esriGeocoderResultEven:focus, .simpleGeocoder .esriGeocoderResultOdd:focus {
    background-color: #EDEDED;
}
esriGeocoderResultFirstThe first result in the results menu.
esriGeocoderResultLastThe last result in the results menu.
.simpleGeocoder .esriGeocoderResultLast {
    border-radius: 0 0 5px 5px;
}
esriGeocoderResultOddAn odd item in the results menu.
.arcgisGeocoder .esriGeocoderResult:hover, .arcgisGeocoder .esriGeocoderResultEven:focus, .arcgisGeocoder .esriGeocoderResultOdd:focus {
    background-color: #D9E7FA;
}
esriGeocoderResultPartialPartially matched text inside the result item.
.arcgisGeocoder .esriGeocoderResult .esriGeocoderResultPartial {
    font-weight: 700;
}
esriGeocoderResultsThe results menu container.
 .arcgisGeocoder .esriGeocoderResults {
    background: none repeat scroll 0 0 #FFFFFF;
    border-color:  #8B8B8B;
}
esriGeocoderSearchThe search button.
.arcgisGeocoder .esriGeocoder .esriGeocoderSearch {
    background: url("../dijit/images/arcgisGeocoder.png") no-repeat scroll 0 0 transparent;
    cursor: pointer;
}
esriGeocoderSelectedThe geocoder item that is currently selected.
esriGeocoderSelectedCheckCheck mark node for currently selected geocoder item.
.arcgisGeocoder .esriGeocoderMenu .esriGeocoderSelectedCheck {
    float: right;
    height: 16px;
    margin: 0 0 0 5px;
    width: 16px;
}

Properties

NameTypeSummary
activeGeocoderObjectCurrently selected locator object.
activeGeocoderIndexNumberCurrent locator index to search by default.
autoCompleteBooleanWhen true, the auto-complete menu is enabled.
autoNavigateBooleanWhen true, the widget will navigate to the selected location.
geocoderMenuBooleanWhen true the geocoder menu is enabled.
geocodersObject[]List of geocoders the widget uses to find search results.
graphicsLayerGraphicsLayerSpecify a graphicsLayer to use when highlightLocation is true.
highlightLocationBooleanIndicates whether to show a graphic at a selected location.
maxLocationsNumberMaximum number of locations to display in the results menu.
minCharactersNumberMinimum number of characters required before the query is performed.
resultsObject[]Current results from query or select.
searchDelayNumberDelay in milliseconds before each keyUp calls for the query to be performed.
showResultsBooleanWhen true, suggestions are displayed as the user is typing.
symbolSymbolSymbol to use when highlightLocation is true.
themeStringCurrent theme being used to style the widget.
valueStringCurrent value of the input textbox.
zoomScaleNumberScale to zoom to when geocoder does not return an extent.

Methods

NameReturn typeSummary
blur()NoneUnfocus the widget's text input.
clear()NoneClears the values currently set in the widget.
destroy()NoneReleases all the resources used by the widget.
find()PromiseExecutes a search using the current value of the geocoder.
focus()NoneBrings focus to the widget's text input.
hide()NoneHide the widget.
select(result)NoneSelect a result using a result object.
show()NoneShow the widget.
startup()NoneFinalizes the creation of the widget.

Events

[ On Style Events | Connect Style Event ]
All On Style event listeners receive a single event object. Additionally, the event object also contains a 'target' property whose value is the object which fired the event.

Events

NameEvent ObjectSummary
auto-complete
{
  results : <Object>
}
Fired when results are returned from an auto-complete.
clearFired when a result is cleared from the input box or a new result is selected.
find-results
{
  results: <Object>
}
Fired when results are returned from a search.
geocoder-select
{
  geocoder: <Object>
}
Fired when a geocoder is selected.
select
{
  results: <Object>
}
Fired when a result has been selected, the submit button is pressed, or the enter key is fired.
Constructor Details

new Geocoder(params, srcNodeRef)

Create a new Geocoder widget using the given DOM node.
Parameters:
<Object> params Required Set of parameters used to specify Geocoder options. See the params properties below for details.
<Node | String> srcNodeRef Required Reference or id of the HTML element where the widget should be rendered.
params properties:
<Boolean | Object> arcgisGeocoder Optional By default, the Geocoder widget uses the Esri World Locator to find search locations. Disable this locator by setting this property to false. See arcgisGeocoder in the object specifications tables below for details.
<Boolean> autoComplete Optional When false, the geocoder will not display the auto-complete results menu. The default value is false.
<Boolean> autoNavigate Optional When false, the geolocator will not navigate to the result after selection or search. The default value is true.
<Boolean> geocoderMenu Optional When false, the geocoder menu will not be displayed when more than one geocoder is set. The default value is false.
<Object[]> geocoders Optional Defines the geocoders that will be used by the Geocoder widget. If arcgisGeocoder is true then the geocoders will be used alongside the default arcgisGeocoder. When false, the default arcgisGeocoder will not be used.

Geocoders is an array of objects that define the additional geocoders. Each object includes the name, url to the locator service, the name of the field setup to accept single line input. i.e. 'SingleLineFieldName' or 'SingleLine', and as of version 3.11, categories as an optional property to limit the types of places for which the service searches.
require([
  "esri/map", "esri/dijit/Geocoder", ... 
], function(Map, Geocoder, ... ) {
  var map = new Map( ... );
  var geocoders = [{
    url: "http://www.example.com/ArcGIS/rest/services/Locators/TA_Address_EU/GeocodeServer",
    name: "EU Geocoder",
    singleLineFieldName: "Single Line Input",
    categories: ["airports"]

}];
var geocoder = new Geocoder({ map: map, geocoders: geocoders, arcgisGeocoder: false },"search"); ... });
<GraphicsLayer> graphicsLayer Optional Specify a graphicsLayer to use when highlightSymbol is true. By default this is null and the graphic will be added to map.graphics. Added at v3.11
<Boolean> highlightLocation Optional Indicates whether to show a graphic at a selected location. Added at v3.11
<Map> map Required Reference to the map. This parameter is always required.
<Number> maxLocations Optional Maximum number of results to return. The default is 6.
<Number> minCharacters Optional Minimum number of characters entered into the search field before querying for results. Default value is 3.
<Number> searchDelay Optional Number of milliseconds before querying for results will begin. Default value is 350.
<Boolean> showResults Optional When false, the geocoder will not show search suggestions while typing.  The default value is true.
<Symbol> symbol Optional Symbol to use when highlightLocation is true. Added at v3.11
<String> theme Optional Specify a theme for the geocoder. The widget has two out-of-the-box themes: simpleGeocoder and arcgisGeocoder. The default theme is simpleGeocoder. Create a custom theme by adding css classes for your them.
.myTheme .esriGeocoder{
  border: solid 1px #000;
}
<String> value Optional Start the geocoder with a default value.
<Number> zoomScale Optional Scale to zoom to when geocoder does not return an extent. The geocoder will create an extent based on the scale supplied and the geometry returned. Default: 10000.
Object Specifications:
<arcgisGeocoder>
<String[]> categories Required Use this to filter out unwanted geocode results with the specified category. See the REST API documentation on category filtering for additional information. Added at v3.11
<Object> localSearchOptions Required Local search options. See the localSearchOptions table below for details.
<String> name Required Name of the geocoder. If you've specified multiple geocoders this is the name that will appear in the dropdown list.
<String> outFields Required An optional list of out fields.
<String> placeholder Required Placeholder text that will appear in the input box. Not supported by IE9 and below.
<String> prefix Required Text that will be prepended to the search string. Note that since the text is appended you may need to add a space to the end of your prefix string. For example prefix: "coffee".
<Extent> searchExtent Required Restrict the search to the specified extent.
<String> sourceCountry Required Country code to use for the search. Using a country code can improve location search performance. Specify the sourceCountry using a valid country code from this list.
<String> suffix Required Text that will be appended to the search string. Note that since the text is appended you may need to add a space to the beginning of your suffix string. For example suffix: "Charlotte, NC".
<String> url Required Url of the geocoder. When undefined the ArcGIS World Geocoder is used.
<localSearchOptions>
<Number> distance Required Specify a search distance for the location search. The default value is 12,000 meters.
<Number> minScale Required Location search will be performed when the map scale is less than the specified value. The default minScale is 15,000.
Sample:
require([
  "esri/map", "esri/dijit/Geocoder", ... 
], function(Map, Geocoder, ... ) {
  var map = new Map( ... );
  var geocoder = new Geocoder({
    map: map
  },"search");
});
Property Details

<Object> activeGeocoder

Currently selected locator object.

<Number> activeGeocoderIndex

Current locator index to search by default. Defaults to 0 when initialized.

<Boolean> autoComplete

When true, the auto-complete menu is enabled.
Known values: true | false

<Boolean> autoNavigate

When true, the widget will navigate to the selected location.
Known values: true | false

<Boolean> geocoderMenu

When true the geocoder menu is enabled.
Known values: true | false

<Object[]> geocoders

List of geocoders the widget uses to find search results.

<GraphicsLayer> graphicsLayer

Specify a graphicsLayer to use when highlightLocation is true. By default this is null and the graphic will be added to map.graphics. (Added at v3.13)

<Boolean> highlightLocation

Indicates whether to show a graphic at a selected location. (Added at v3.11)
Known values: true | false
Default value: false

<Number> maxLocations

Maximum number of locations to display in the results menu.

<Number> minCharacters

Minimum number of characters required before the query is performed.

<Object[]> results

Current results from query or select. Defaults to an empty array.

<Number> searchDelay

Delay in milliseconds before each keyUp calls for the query to be performed.

<Boolean> showResults

When true, suggestions are displayed as the user is typing.
Known values: true | false

<Symbol> symbol

Symbol to use when highlightLocation is true. (Added at v3.11)

<String> theme

Current theme being used to style the widget.

<String> value

Current value of the input textbox.

<Number> zoomScale

Scale to zoom to when geocoder does not return an extent. The geocoder will create an extent based on the scale supplied and the geometry returned. (Added at v3.8)
Default value: 10000
Method Details

blur()

Unfocus the widget's text input.

clear()

Clears the values currently set in the widget.

destroy()

Releases all the resources used by the widget. Call this method when this instance of the widget is no longer needed in your application.

find()

Executes a search using the current value of the geocoder.
Return type: Promise

focus()

Brings focus to the widget's text input.

hide()

Hide the widget.

select(result)

Select a result using a result object.
Parameters:
<Object> result Required An object with the following properties.
{
  extent: <Extent>,
  feature: <Feature>,
  name: <String>
}

show()

Show the widget.

startup()

Finalizes the creation of the widget. Call this method after the constructor for the widget is called and before interacting with the widget.
Sample:
require([
  "esri/dijit/Geocoder", ... 
], function(Geocoder, ... ) {
  var geocoder = new Geocoder({
    map: map
  },"search");
  geocoder.startup();
  ...
});
Event Details
[ On Style Events | Connect Style Event ]

auto-complete

Fired when results are returned from an auto-complete. (Added at v3.6)
Event Object Properties:
<Object> results A results object with the following properties:
{
  results: [
    extent: <Extent>,
    feature: <Feature>,
    name: <String>
  ],
  value: <String>
}

clear

Fired when a result is cleared from the input box or a new result is selected. (Added at v3.6)

find-results

Fired when results are returned from a search. (Added at v3.6)
Event Object Properties:
<Object> results An object containing the results of the search.
{
  results: [
    extent: <Extent>,
    feature: <Feature>,
    name: <String>
  ],
  value: <String>
}

geocoder-select

Fired when a geocoder is selected. (Added at v3.6)
Event Object Properties:
<Object> geocoder An object that defines the selected geocoder.
{
  url: <String>,
  name: <String>,
  placeholder: <String>,
  outFields: <String>,
  prefix: <String>,
  suffix: <String>,
  searchExtent: <Extent>,
  sourceCountry: <String>
}

select

Fired when a result has been selected, the submit button is pressed, or the enter key is fired. (Added at v3.6)
Event Object Properties:
<Object> results Returns a result object with the following properties:
{
extent: <Extent>,
feature: <Feature>,
name: <String>
}