Feb 11, 2015

map-autocomplete

Autocomplete Map Search

Autocomplete multi-source Search with ArcGIS REST services

Search First. Search is expected in modern web applications. And what better use of a map application than to start typing what you want, be shown a list of relevant suggestions, pick one, and be taken there with some useful context info.

In several posts on the great geospatial blog MapBrief, Brian Timoney has discussed a Search First approach to web application building. The most recent example:

Good Thing #1: A Big, Obvious Auto-Complete Text Entry Box

I couldn’t agree more. It is core to nearly every application I build and is far more useful than most novelty web mapping “standard” tools (looking at you, measure tool).

Search is the number one request I get in web mapping applications, so I thought I’d share how I put the pieces together to get an autocomplete search working with ArcGIS REST services.

I’ll walk through the steps to get a fully functioning autocomplete map search feature.

Source on GitHub:
https://github.com/brightrain/arcgis-autocomplete

Sample application:
http://dev.brightrain.com/map-autocomplete

Let’s build an autocomplete search box for recreation sites in Okanogan–Wenatchee National Forest.

This solution uses twitter typeahead.js. The bundled download includes the Bloodhound suggestion engine and the jQuery plugin, all of which we’ll use.

Once typeahead is included in your app, the only HTML you need is:

<input id="search-box" type="text" placeholder="Search...">

There are three parts to getting things going:

Define and initialize suggestion engines
Wire up typeahead with jQuery
Handle the event when a user selects a suggestion

Define the Engines

We define a Bloodhound engine for each data source. In this example we used four:

Campground feature layer
Trailhead feature layer
Ski area feature layer
Esri World Geocoder

Construct the remote sources

The remote source defines the URL that will be called as the user types.

ArcGIS REST options:

find
Use this if you have a MapServer and want to search multiple layers at once.
API docs:
http://resources.arcgis.com/en/help/arcgis-rest-api/index.html#/Find/02r3000000zm000000/

query
Use this if you only have a FeatureServer. Query a layer or query the whole feature service.
Examples:
http://resources.arcgis.com/en/help/arcgis-rest-api/#/Query_Feature_Service_Layer/02r3000000r1000000/
http://resources.arcgis.com/en/help/arcgis-rest-api/#/Query_Feature_Service/02r3000000w5000000/

suggest
Best for geocoding.
Docs:
https://developers.arcgis.com/rest/geocode/api-reference/geocoding-suggest.htm

You can roll your own locator that supports Suggest (ArcGIS 10.3+).
We’ll use the World Geocoder and Suggest.

Campground engine example:
https://gist.github.com/brightrain/9f7efde8f77a63ca5125

World geocoder engine example (note the searchExtent parameter):
https://gist.github.com/2036ceb58860266d5658

Both engines use the ajax property to show a spinner before the request and remove it afterward.

Add the engines and style the suggestions

Turn the input box into a typeahead via jQuery:

https://gist.github.com/25d3eed98a6d5c8defca

Then register each engine with typeahead:

Campground setup example:
https://gist.github.com/a4ea462113062598749b

The full chained list of all engines:
https://gist.github.com/23f4f68a0f3ed79c6fc8

Define what happens when a user selects a suggestion

We set up a jQuery event handler chained to the typeahead declaration. The event handler receives:

the element
the selected datum

For feature service layers, the datum includes the objectId. This allows a second request to fetch the feature and its geometry. In the sample we zoom to it and place a text label.

For the geocoder, the datum includes a magicKey, which can be used to retrieve the full feature via a find call.

Full event handler:
https://gist.github.com/brightrain/4b07b5f3fa4d9a2d85f2