L.esri.Geocoding.Geosearch

Extends L.Control

L.esri.Geocoding.Geosearch is a control for auto-complete enabled search. You can find more information and the source code for this plugin here.

Constructor

Constructor Description
L.esri.Geocoding.geosearch(<GeosearchObject> options)

Creates a new Geosearch control

Options

Option Type Default Description
position String 'topleft' Expects a valid Leaflet control position.
zoomToResult Boolean true Determines whether or not the map will zoom to the result after geocoding is complete.
useMapBounds Boolean or Integer 12 Determines if and when the geocoder should use the bounds of the map to filter search results. If true the geocoder will always return results in the current map bounds. If false it will always search the world. If an integer (like 11) is passed, the geocoder will use the bounds of the map for searching only if the map is currently zoomed in far enough.
collapseAfterResult Boolean true Determines whether or not the geocoder should collapse after a result is found.
expanded Boolean false Determines whether or not the geocoder starts in an expanded state.
allowMultipleResults Boolean true If set to true and the user submits the form without a suggestion, the control will geocode the current text in the input.
providers Array See description An array of providers to search.
placeholder String 'Search for places or addresses' Placeholder text for the search input.
title String 'Location Search' Title text for the search input. Shows as a tooltip on hover.
searchBounds L.latLngBounds null If set, the geocoder will filter results using the provided static bounding box regardless of the current zoom level of the map, overriding useMapBounds entirely.

Events

Event Data Description
results <ResultsEvent> Fired when results are returned from the geocoder.

Events from each provider will match the events fired by L.esri.Service.

Methods

Method Returns Description
clear() this Clears the current text and collapses the control if collapseAfterResult is true.
disable() grays out the input so that addresses cannot be searched.
enable() ungray the input so that addresses can once again be searched.

Styling

For reference here is the internal DOM structure of the geocoder

<div class="geocoder-control leaflet-control">
  <input class="geocoder-control-input leaflet-bar">
  <ul class="geocoder-control-suggestions leaflet-bar">
    <li class="geocoder-control-suggestion geocoder-control-selected">The Selected Result</li>
    <li class="geocoder-control-suggestion">Another Result</li>
  </ul>
</div>

By default, ellipses are shown when the text of suggestions is too long. However, you may want to show the entire suggestions text.

The following CSS rule will show the entire suggestions text, broken onto multiple lines. You will need to add the rule in your own custom stylesheet associated with your project:

.geocoder-control-suggestions .geocoder-control-suggestion {
  overflow-wrap: break-word;
  word-break: break-all;
  overflow: visible;
  white-space: break-spaces;
}

Example

Live sample here.

Providers

The Geosearch control can also search for results from a variety of sources including Feature Layers and Map Services. This is done with plain text matching and is not "real" geocoding. But it allows you to mix custom results into a search box.

<link rel="stylesheet" href="./esri-leaflet-geocoder.css">
<script src="./esri-leaflet-geocoder.js"></script>
var arcgisOnline = L.esri.Geocoding.arcgisOnlineProvider({
    // API Key to be passed to the ArcGIS Online Geocoding Service - https://developers.arcgis.com
    apikey: 'YOUR_API_KEY'
});

var gisDay = L.esri.Geocoding.featureLayerProvider({
  url: 'https://services.arcgis.com/uCXeTVveQzP4IIcx/arcgis/rest/services/GIS_Day_Final/FeatureServer/0',
  searchFields: ['Name', 'Organization'], // Search these fields for text matches
  label: 'GIS Day Events', // Group suggestions under this header
  formatSuggestion: function (feature) {
    return feature.properties.Name + ' - ' + feature.properties.Organization; // format suggestions like this.
  }
});

L.esri.Geocoding.Controls.geosearch({
  providers: [arcgisOnline, gisDay] // will geocode via ArcGIS Online and search the GIS Day feature service.
}).addTo(map);

Available Providers

  • L.esri.Geocoding.arcgisOnlineProvider
    uses the ArcGIS Online World Geocoding service.

  • L.esri.Geocoding.featureLayerProvider
    gets results by querying a Feature Layer for text matches.

  • L.esri.Geocoding.mapServiceProvider
    uses the find and query methods of ArcGIS Server Map Services to get text matches.

  • L.esri.Geocoding.geocodeServiceProvider
    uses an ArcGIS Server Geocode Service (and supports suggestions from ArcGIS Server 10.3+ enabled endpoints).

All providers share the following options:

Option Type Default Description
label String 'Provider Type' Text that will be used to group suggestions (when more than one provider is used).
maxResults Integer 5 Maximum number of results to show for the provider. Hard limit for suggestions from the ArcGIS World Geocoding Service is 15.
attribution string Varies by provider Adds attribution to the map to credit the source.
apikey String null Will use this api key to authenticate all calls to the service.
token String null Will use this token to authenticate all calls to the service.
arcgisOnlineProvider
Option Type Default Description
countries String [Strings] null Limit results to one or more countries. Any ISO 3166 2 or 3 digit country code supported by the ArcGIS World Geocode service is allowed. Note: using an array of country codes may result in inaccurate results even when a specific suggestion is supplied.
categories String [Strings] null Limit results to one or more categories. See the list of valid categories for possible values.
forStorage Boolean false Indicates whether results will be stored permanently. More information can be found here.

Results from the arcgisOnlineProvider will have an additional properties key which will correspond with all available fields in the World Geocode service

geocodeServiceProvider
Option Type Default Description
url String Required The URL for the service that will be searched.
label String 'Geocode Service' Text that will be used to group suggestions under when more than one provider is being used.

Results from the geocodeServiceProvider will have an additional properties key which will correspond with all the available fields in the service.

featureLayerProvider
Option Type Default Description
url String Required The URL for the service that will be searched.
searchFields String Array[Strings] None An array of fields to search for text.
formatSuggestion Function See Description Formatting function for the suggestion text. Receives feature information and returns a string.
bufferRadius Integer 1000 If a service or layer contains points, buffer points by this radius (in meters) to create bounds.
searchMode String 'contain' Sets how the search is performed against features. Options are contain, startWith, endWith, or strict. Please refer to the FeatureLayer Provider JavaScript file for how the different searches are structed.
featureLayerProvider Methods
Method Returns Description
orderBy(<String> fieldname, <String> order) this Sort output features using values from an individual field. "ASC" (ascending) is the default sort order, but "DESC" can be passed as an alternative. This method can be called more than once to apply advanced sorting.

Results from the featureLayerProvider will have an additional properties key which will contain all the information for the feature and a geojson key that will contain a GeoJSON representation of the feature.

mapServiceProvider
Option Type Default Description
url String Required The URL for the service that will be searched.
searchFields String Array[Strings] None An array of fields to search for text.
layers Integer Array[Integers] [0] An array of layer identifiers to find text matches on.
formatSuggestion Function See Description Formatting function for the suggestion text. Receives feature information and returns a string.
bufferRadius Integer Array[Integers] Buffer point results by this radius to create bounds.

Results from the mapServiceProvider will have an additional properties key which will contain all the information for the feature and a geojson key that will contain a GeoJSON representation of the feature.

Events from each provider will match the events fired by L.esri.Service.

Results

Property Type Description
bounds L.LatLngBounds The bounds around this suggestion. Helpful for zooming to results like cities and states.
latlng L.LatLng The center of the results.
text String The entered search text.
results [<ResultObject>] An array of result objects.

Result Object

A single result from a provider. You should not rely on all these properties being present in every result object. Some providers may add additional properties.

Property Type Description
text String The text that was passed to the provider.
bounds L.LatLngBounds The bounds around this result. Helpful for zooming to results like cities and states.
latlng L.LatLng The center of the result.

The result object will also contain any additional properties from the provider. See the available providers for more information.

Edit this page on GitHub