Esri Leaflet Geocoder

The Esri Leaflet Geocoder is a small series of API helpers and UI controls to interact with the ArcGIS Online geocoding services.

Currently Esri Leaflet Geocoder is in development and should be thoguht of as a beta or preview

Esri Leaflet Geocoder relies on the minimal Esri Leaflet Core which handles abstraction for requests and authentication when neccessary. You can fine out more about teh Esri Leaflet Core on the Esri Leaflet downloads page.

Example

Take a look at the live demo.

<!DOCTYPE html>
<html>
  <head>
    <title>Esri Leaflet Geocoder</title>

    <!-- Load Leaflet from their CDN -->
    <link rel="stylesheet" href="http://cdn.leafletjs.com/leaflet-0.7.3/leaflet.css" />
    <script src="http://cdn.leafletjs.com/leaflet-0.7.3/leaflet-src.js"></script>

    <!-- Make the map fill the entire page -->
    <style>
      #map {
        position: fixed;
        top: 0;
        bottom: 0;
        left: 0;
        right: 0;
      }
    </style>

    <!-- Esri Leaflet Core -->
    <script src="http://cdn-geoweb.s3.amazonaws.com/esri-leaflet/0.0.1-beta.5/esri-leaflet-core.js"></script>

    <!-- Esri Leaflet Geocoder -->
    <script src="http://cdn-geoweb.s3.amazonaws.com/esri-leaflet-geocoder/0.0.1-beta.3/esri-leaflet-geocoder.js"></script>
    <link rel="stylesheet" type="text/css" href="http://cdn-geoweb.s3.amazonaws.com/esri-leaflet-geocoder/0.0.1-beta.3/esri-leaflet-geocoder.css">
  </head>
  <body>
    <div id="map"></div>
    <script>
      var map = L.map('map').setView([45.5165, -122.6764], 12);

      var tiles = L.tileLayer("http://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png").addTo(map);

      // create the geocoding control and add it to the map
      var searchControl = new L.esri.Controls.Geosearch().addTo(map);

      // create an empty layer group to store the results and add it to the map
      var results = new L.LayerGroup().addTo(map);

      // listen for the results event and add every result to the map
      searchControl.on("results", function(data){
        results.clearLayers();
        for (var i = data.results.length - 1; i >= 0; i--) {
          results.addLayer(L.marker(data.results[i].latlng));
        };
      });
    </script>
  </body>
</html>

L.esri.Controls.Geosearch

Constructor

Extends L.Control

Constructor	Options	Description
`new L.esri.Controls.Geosearch(options)` `L.esri.Controls.geosearch(options)`	`<GeosearchOptions>`	Creates a new Geosearch control.

Options

Option	Type	Default	Description
`position`	`String`	`topleft`	One of the valid Leaflet control positions.
`zoomToResult`	`Boolean`	`true`	If `true` the map will zoom the result after geocoding is complete.
`useMapBounds`	`Boolean` or `Integer`	`12`	Determines if and when the geocoder should begin using the bounds of the map to enchance 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 in the geocoder will use the bounds of the map for searching if the map is at a zoom level equal to or greater than the integer. This mean the geocoder will prefer local results when the map is zoomed in.
`collapseAfterResult`	`Boolean`	`true`	If the geocoder is expanded after a result this will collapse it.
`expanded`	`Boolean`	`true`	Start the control in an expanded state.
`maxResults`	`Integer`	`25`	The maximum number of results to return from a geocoding request. Max is 50.
`token`	`String`	`false`	A token to pass with requests.
`forStorage`	`Boolean`	`true`	You must set this to true if you intend for your users to store the results of your results.
`allowMultipleResults`	`Boolean`	`true`	If set to `true` and the user submits the form without a suggestion selected geocodes the current text in the input and zooms the user to view all the results.

You can also pass any options you can pass to L.esri.Services.Geocoding.

Methods

Method	Options	Description
`clear()`	`null`	Clears the text currently in the geocoder and collapses it if `collapseAfterResult` is true.

Events

Event	Data	Description
`load`	`null`	A generic event fired when a request to the geocoder starts.
`loading`	`null`	A generic event fired when a request to the geocoder finished.
`results`	`<ResultsEvent>`	Fired when a result is returned from the geocoder.

Styling

For reference here is the internal 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>

Results Event

Property	Type	Description
`bounds`	`L.LatLngBounds`	The bounds arround this suggestion. Good for zooming to results like cities and states.
`latlng`	`L.LatLng`	The center of the result.
`results`	`[<ResultObject>]`	An array of result objects.

Result Object

A single result from the geocoder. You should not rely on all these properties being present in every result object.

Property	Type	Description
`text`	`String`	The text that was passed to the geocoder.
`bounds`	`L.LatLngBounds`	The bounds arround this suggestion. Good for zooming to results like cities and states.
`latlng`	`L.LatLng`	The center of the result.
`name`	`String`	Name of the geocoded place. Usually something like "Paris" or "Starbucks".
`match`	`String`	What was matched internally in the geocoder. Cooresponded to the `Addr_type` field in the geocoding service.
`country`	`String`	The country the geocoded place is located in.
`region`	`String`	The largest administrative area for a country that the geocoded palce is in, typically a state or province.
`subregion`	`String`	The next largest administrative area for a the geocoded place, typically a county or region.
`city`	`String`	The city the geocoded place is located in.
`address`	`String`	Complete address returned for the geocoded place. The format is based on address standards for the country within which the address is located.

L.esri.Services.Geocoding

A basic wrapper for ArcGIS Online geocoding services. Used internally by L.esri.Controls.Geosearch.

Constructor

Constructor	Options	Description
`new L.esri.Services.Geocoding(url, options)` `L.esri.Controls.geosearch(url, options)` `new L.esri.Services.Geocoding(options)` `L.esri.Controls.geosearch(options)`	`<GeosearchOptions>`	Creates a new Geosearch control you can pass the url as the first parameter or as `url` in the options to a custom geocoding enpoint if you do no want to use the ArcGIS Online World Geocoding service.

Options

Option	Type	Default	Description
`url`	`String`	`<WorldGeocodeServiceURL>`	Defaults to the ArcGIS World Geocoding service.

You can also pass any options you can pass to L.esri.Services.Service.

Methods

Method	Options	Description
`geocode(text, object, callback)`	`<GeocodeOptions>`	Geocodes the specified `text` with the passed [<GeocodeOptions>``](#geocode-options). callback`will be called with`error`, [`Geocode Results`](geocode-results) and` response` as the parameters.
`suggest(text, object, callback)`	`<SuggestOptions>`	Suggests results for `text` with the given `<SuggestOptions>`. `callback` will be called with `error` and `response` parameters.
`reverse(latlng, object, callback)`	`<ReverseOptions>`	Suggests results for `text` with the given `<ReverseOptions>`. `callback` will be called with `error`, `Reverse Geocode Result` and `response` as the parameters.

Events

Event	Data	Description
`load`	`null`	A generic event fired when a request to the geocoder begins.
`loading`	`null`	A generic event fired when a request to the geocoder is finished.

Geocode Options

The geocode method can accept any options from the geocode service with the exception of text.

Suggest Options

The suggest method can accept any options from the suggest service with the exception of text.

Reverse Geocode Options

The suggest method can accept any options from the reverse geocoding service with the exception of location.

Geocode Results

Geocode results conform to the following format

[
  {
    text: 'Text',
    bounds: L.LatLngBounds,
    latlng: L.LatLng,
    name: 'PlaceName',
    match: 'AddressType',
    country: 'Country',
    region: 'Region',
    subregion: 'Subregion',
    city: 'City',
    address: 'Address'
  }
]

Reverse Geocode Result

Reverse geocoding results conform to the following format

{
  latlng: L.LatLng,
  address: 'Address',
  neighborhood: 'Neighborhood',
  city: 'City',
  subregion: 'Subregion',
  region: 'Region',
  postal: 'Postal',
  postalExt: 'PostalExt',
  countryCode: 'CountryCode'
}

Development Instructions

Fork and clone Esri Leaflet Geocoder
cd into the esri-leaflet-geocoder folder
Instal the dependancies with npm install
The example at /index.html should work
Make your changes and create a pull request

Dependencies

Esri Leaflet Geocoder relies on the minimal Esri Leaflet Core which handles abstraction for requests and authentication when neccessary. You can fine out more about teh Esri Leaflet Core on the Esri Leaflet downloads page.

Resources

Geocoding Service Documentation
ArcGIS for Developers
ArcGIS REST Services
twitter@esri

Issues

Find a bug or want to request a new feature? Please let us know by submitting an issue.

Contributing

Esri welcomes contributions from anyone and everyone. Please see our guidelines for contributing.

Terms and Conditions

In order the use the ArcGIS Online Geocoding Service you should signup for an ArcGIS for Developers account or purchase an ArcGIS Online Organizational Subscription.

Once you have an account you are good to go. Thats it!
Your users can search for as many places as they want. Esri defines this as "Geosearch" and its free. You only consume credits when you want to store the result of geocodes.
You are allowed to store the results of any geocoding you do if you pass the forStorage flag and a valid access token.
If you use this library in a revenue generating application or for goverment use you must upgrade to a paid account. You are not allowed to generate revenue while on a free plan.

This information is from the ArcGIS for Developers Terms of Use FAQ and the ArcGIS Online World Geocoder documentation

Licensing

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

A copy of the license is available in the repository's license.txt file.

[](Esri Tags: ArcGIS Web Mapping Leaflet Geocoding) [](Esri Language: JavaScript)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Esri Leaflet Geocoder

Example

L.esri.Controls.Geosearch

Constructor

Options

Methods

Events

Styling

Results Event

Result Object

L.esri.Services.Geocoding

Constructor

Options

Methods

Events

Geocode Options

Suggest Options

Reverse Geocode Options

Geocode Results

Reverse Geocode Result

Development Instructions

Dependencies

Resources

Issues

Contributing

Terms and Conditions

Licensing

Files

README.md

Latest commit

History

README.md

File metadata and controls

Esri Leaflet Geocoder

Example

L.esri.Controls.Geosearch

Constructor

Options

Methods

Events

Styling

Results Event

Result Object

L.esri.Services.Geocoding

Constructor

Options

Methods

Events

Geocode Options

Suggest Options

Reverse Geocode Options

Geocode Results

Reverse Geocode Result

Development Instructions

Dependencies

Resources

Issues

Contributing

Terms and Conditions

Licensing