Hide Table of Contents
esri
esri/arcgis
esri/dijit
esri/dijit/analysis
esri/dijit/geoenrichment
esri/dijit/geoenrichment/ReportPlayer
esri/geometry
esri/layers
esri/renderers
esri/symbols
esri/tasks
esri/tasks/datareviewer
esri/tasks/geoenrichment
esri/tasks/locationproviders
Class: Geocoder
[ AMD Module Require | Legacy Module Require ]
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
| Name | Summary |
|---|---|
| new Geocoder(params, srcNodeRef) | Create a new Geocoder widget using the given DOM node. |
CSS
esri/dijit/Geocoder | Download source
| Name | Description |
|---|---|
| esriGeocoder | Represents 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;
} |
| esriGeocoderActive | The 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; } |
| esriGeocoderClearFloat | Style's that are used to clear floats in the Geocoder widget. |
| esriGeocoderContainer | The containing class for the geocoder node. |
| esriGeocoderHasValue | Added to the DOM node when the geocoder has a value. |
| esriGeocoderIcon | Represents an icon node. .arcgisGeocoder .esriGeocoderIcon { display: block; float: right; height: 16px; margin: 2px 5px 2px 0; outline: 0 none; overflow: hidden; width: 16px; } |
| esriGeocoderLoading | Defines the loading spinner that displays in the textbox. .arcgisGeocoder .esriGeocoderLoading .esriGeocoderReset { background: url("../dijit/images/loading.gif") no-repeat scroll center center transparent; } |
| esriGeocoderMenu | The geocoder menu. .arcgisGeocoder .esriGeocoderMenu { background: none repeat scroll 0 0 #FFFFFF; border-right: 1px solid #8B8B8B; border-width: 0 1px 1px; } |
| esriGeocoderMenuActive | Displayed when the geocoder menu is shown. .arcgisGeocoder .esriGeocoderActive, .arcgisGeocoder .esriGeocoderMenuActive { border-bottom: 0 none; } |
| esriGeocoderMenuArrow | The 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; } |
| esriGeocoderMenuClose | The close button on the geocoder menu. .arcgisGeocoder .esriGeocoderMenu .esriGeocoderMenuClose { background: url("../dijit/images/arcgisGeocoder.png") no-repeat scroll -64px 0 transparent; } |
| esriGeocoderMenuHeader | The geocoder menu header. .arcgisGeocoder .esriGeocoderMenu .esriGeocoderMenuHeader { border-bottom: 1px solid #8B8B8B; color: #000000; } |
| esriGeocoderMultiple | Represents the styles for multiple geocoders.
.simpleGeocoder .esriGeocoderMultiple input {
width: 146px;
} |
| esriGeocoderReset | The reset button .arcgisGeocoder .esriGeocoderHasValue .esriGeocoderReset { background: url("../dijit/images/arcgisGeocoder.png") no-repeat scroll -48px 0 transparent; } |
| esriGeocoderResult | An item in the result menu. .arcgisGeocoder .esriGeocoderResult { cursor: pointer; display: block; padding: 5px; text-overflow: ellipsis; white-space: nowrap; } |
| esriGeocoderResultEven | An even item in the results menu. .simpleGeocoder .esriGeocoderResult:hover, .simpleGeocoder .esriGeocoderResultEven:focus, .simpleGeocoder .esriGeocoderResultOdd:focus { background-color: #EDEDED; } |
| esriGeocoderResultFirst | The first result in the results menu. |
| esriGeocoderResultLast | The last result in the results menu. .simpleGeocoder .esriGeocoderResultLast { border-radius: 0 0 5px 5px; } |
| esriGeocoderResultOdd | An odd item in the results menu. .arcgisGeocoder .esriGeocoderResult:hover, .arcgisGeocoder .esriGeocoderResultEven:focus, .arcgisGeocoder .esriGeocoderResultOdd:focus { background-color: #D9E7FA; } |
| esriGeocoderResultPartial | Partially matched text inside the result item. .arcgisGeocoder .esriGeocoderResult .esriGeocoderResultPartial { font-weight: 700; } |
| esriGeocoderResults | The results menu container. .arcgisGeocoder .esriGeocoderResults { background: none repeat scroll 0 0 #FFFFFF; border-color: #8B8B8B; } |
| esriGeocoderSearch | The search button. .arcgisGeocoder .esriGeocoder .esriGeocoderSearch { background: url("../dijit/images/arcgisGeocoder.png") no-repeat scroll 0 0 transparent; cursor: pointer; } |
| esriGeocoderSelected | The geocoder item that is currently selected. |
| esriGeocoderSelectedCheck | Check mark node for currently selected geocoder item. .arcgisGeocoder .esriGeocoderMenu .esriGeocoderSelectedCheck { float: right; height: 16px; margin: 0 0 0 5px; width: 16px; } |
Properties
| Name | Type | Summary |
|---|---|---|
| activeGeocoder | Object | Currently selected locator object. |
| activeGeocoderIndex | Number | Current locator index to search by default. |
| autoComplete | Boolean | When true, the auto-complete menu is enabled. |
| autoNavigate | Boolean | When true, the widget will navigate to the selected location. |
| geocoderMenu | Boolean | When true the geocoder menu is enabled. |
| geocoders | Object[] | List of geocoders the widget uses to find search results. |
| graphicsLayer | GraphicsLayer | Specify a graphicsLayer to use when highlightLocation is true. |
| highlightLocation | Boolean | Indicates whether to show a graphic at a selected location. |
| maxLocations | Number | Maximum number of locations to display in the results menu. |
| minCharacters | Number | Minimum number of characters required before the query is performed. |
| results | Object[] | Current results from query or select. |
| searchDelay | Number | Delay in milliseconds before each keyUp calls for the query to be performed. |
| showResults | Boolean | When true, suggestions are displayed as the user is typing. |
| symbol | Symbol | Symbol to use when highlightLocation is true. |
| theme | String | Current theme being used to style the widget. |
| value | String | Current value of the input textbox. |
| zoomScale | Number | Scale to zoom to when geocoder does not return an extent. |
Methods
| Name | Return type | Summary |
|---|---|---|
| blur() | None | Unfocus the widget's text input. |
| clear() | None | Clears the values currently set in the widget. |
| destroy() | None | Releases all the resources used by the widget. |
| find() | Promise | Executes a search using the current value of the geocoder. |
| focus() | None | Brings focus to the widget's text input. |
| hide() | None | Hide the widget. |
| select(result) | None | Select a result using a result object. |
| show() | None | Show the widget. |
| startup() | None | Finalizes 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
| Name | Event Object | Summary |
|---|---|---|
| auto-complete | {
results : < | Fired when results are returned from an auto-complete. |
| clear | Fired when a result is cleared from the input box or a new result is selected. | |
| find-results | {
results: < | Fired when results are returned from a search. |
| geocoder-select | {
geocoder: < | Fired when a geocoder is selected. |
| select | {
results: < | Fired when a result has been selected, the submit button is pressed, or the enter key is fired. |
Constructor Details
Create a new Geocoder widget using the given DOM node.
Parameters:
< |
Required | Set of parameters used to specify Geocoder options. See the params properties below for details. |
< |
Required | Reference or id of the HTML element where the widget should be rendered. |
params properties: < |
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. |
< |
Optional | When false, the geocoder will not display the auto-complete results menu. The default value is false. |
< |
Optional | When false, the geolocator will not navigate to the result after selection or search. The default value is true. |
< |
Optional | When false, the geocoder menu will not be displayed when more than one geocoder is set. The default value is false. |
< |
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"]
|
< |
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 |
< |
Optional | Indicates whether to show a graphic at a selected location. Added at v3.11 |
< |
Required | Reference to the map. This parameter is always required. |
< |
Optional | Maximum number of results to return. The default is 6. |
< |
Optional | Minimum number of characters entered into the search field before querying for results. Default value is 3. |
< |
Optional | Number of milliseconds before querying for results will begin. Default value is 350. |
< |
Optional | When false, the geocoder will not show search suggestions while typing. The default value is true. |
< |
Optional | Symbol to use when highlightLocation is true. Added at v3.11 |
< |
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;
}
|
< |
Optional | Start the geocoder with a default value. |
< |
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>< |
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 |
< |
Required | Local search options. See the localSearchOptions table below for details. |
< |
Required | Name of the geocoder. If you've specified multiple geocoders this is the name that will appear in the dropdown list. |
< |
Required | An optional list of out fields. |
< |
Required | Placeholder text that will appear in the input box. Not supported by IE9 and below. |
< |
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". |
< |
Required | Restrict the search to the specified extent. |
< |
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. |
< |
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". |
< |
Required | Url of the geocoder. When undefined the ArcGIS World Geocoder is used. |
<
localSearchOptions>< |
Required | Specify a search distance for the location search. The default value is 12,000 meters. |
< |
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
ObjectCurrently selected locator object.
<Number
NumberCurrent locator index to search by default. Defaults to 0 when initialized.
<Boolean
BooleanWhen true, the widget will navigate to the selected location.
Known values:
true | false<Object[]
Object[]List of geocoders the widget uses to find search results.
<GraphicsLayer
GraphicsLayerSpecify 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
BooleanIndicates whether to show a graphic at a selected location. (Added at v3.11)
Known values:
true | falseDefault value:
false<Number
NumberMaximum number of locations to display in the results menu.
<Number
NumberMinimum number of characters required before the query is performed.
<Object[]
Object[]Current results from query or select. Defaults to an empty array.
<Number
NumberDelay in milliseconds before each keyUp calls for the query to be performed.
<Boolean
BooleanWhen true, suggestions are displayed as the user is typing.
Known values:
true | false<Symbol
SymbolSymbol to use when highlightLocation is true. (Added at v3.11)
<String
StringCurrent theme being used to style the widget.
<String
StringCurrent value of the input textbox.
<Number
NumberScale 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:
10000Method Details
Releases all the resources used by the widget. Call this method when this instance of the widget is no longer needed in your application.
Select a result using a result object.
Parameters:
< |
Required | An object with the following properties.
{
extent: <Extent>,
feature: <Feature>,
name: <String>
}
|
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 ]
Fired when results are returned from an auto-complete. (Added at v3.6)
Event Object Properties:
< |
A results object with the following properties:
{
results: [
extent: <Extent>,
feature: <Feature>,
name: <String>
],
value: <String>
}
|
Fired when a result is cleared from the input box or a new result is selected. (Added at v3.6)
Fired when results are returned from a search. (Added at v3.6)
Event Object Properties:
< |
An object containing the results of the search.
{
results: [
extent: <Extent>,
feature: <Feature>,
name: <String>
],
value: <String>
}
|
Fired when a geocoder is selected. (Added at v3.6)
Event Object Properties:
< |
An object that defines the selected geocoder.
{
url: <String>,
name: <String>,
placeholder: <String>,
outFields: <String>,
prefix: <String>,
suffix: <String>,
searchExtent: <Extent>,
sourceCountry: <String>
}
|
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:
< |
Returns a result object with the following properties: { extent: <Extent>, feature: <Feature>, name: <String> } |