Address Search

Why?

To add an address search to your website or app. It can be configured to search either the world geocoding service or your own ArcGIS Locator.

For example:

  • To allow users to enter a full or partial address to find the area they are interested in (e.g. a property address, a street, a postcode)
  • To allow a user to select the specific property they are interested in (e.g. to pass the UPRN through to another application)

Options

There are two options available adding address searching on your apps:

  • Esri Search Widget (which is part of the JS API). The Esri Search Widget is used as the default address search widget across the ArcGIS platform and used by ArcGIS Online templates and within the WebAppBuilder. As a developer you have control of the position and style of the locator.
  • Drilldown widget (which is an open source widget developed by Esri UK). This provides additional functionality that supports hierarchical searching and forces the user to drilldown through the hierarchy to select a specific entry in the locator. (e.g. if they enter a street they will see a pick list of all the property on the street and can pick the property they want, if the property is divided into sub-properties they will see another pick list of these)

Which?

The main factor affecting the choice of option will be the locator that is being used and the version of LocatorHub that you are using. The requirements are:

LocatorHub 5.3 (or above) and one of the following locators:

  • LLPG
  • IDOX GMS
  • One Scotland Gazetteer

LocatorHub 5.4 (or above) and one of the following locators:

  • Addressbase Premium
  • Merge or Cascade locators using an appropriate standardised schema

You should only use the drilldown widget if you want the user to be forced to select an individual property, for example, if the user enters a street:

  • Use the Search widget if you want your application to go to any matching record on the street
  • Use the drilldown only if you want the user to be forced to select an individual property on the street

Demos

There are three demos showing the Drilldown widget in action available from the links on the right of this page:

  • Drilldown – showing the drilldown widget in use in a simple JS app
  • Web AppBuilder – showing the drilldown widget in use with a Web AppBuilder application
  • Local Perspective – showing the drilldown widget in use within one of Esri ArcGIS Online templates

A demo of how to implement the standard search widget can be seen below, along with details of how the Drilldown and We AppBuilder demos were put together.

How?

The example below is using the JSAPI Search widget linked to a map to display the results. The map itself has been created in ArcGIS online as a webmap and has been embedded by referencing the webmap ID.

The JavaScript API help talks you through the basics of adding a map into a web page in its tutorial which can be accessed here. The main change is that in this page rather than loading the map and defining the layers individually we have already handled all of that when creating our webmap. So instead all we need to add is a reference to our webmap as below.

    // Load the webmap
    var deferred = arcgisUtils.createMap("bea8606595d44ed5a8d82b3b22f6ca09", "map", {
        apOptions: {
            slider: true
        },
        usePopupManager: true,
        geometryServiceURL: "//sampleserver3.arcgisonline.com/ArcGIS/rest/services/Geometry/GeometryServer"
    });

The Search widget needs a reference to the map so once the webmap has loaded we can then create the Search widget.

    // Once the webmap is loaded create the Search widget
    deferred.then(function (response) {
        var s = new Search({
            map: response.map,
            enableSuggestions: true
        }, "search");
        s.startup();
    });

It is possible to set a source for the Search Widget and point it to one of your own locatorss, but in this example by not setting a source it defaults to using the World Geocoder. We have also turned on suggestions to get a list of addresses that match what we type in. For information on setting custom sources for the Search widget and various other properties to control how it behaves see the documentation here

This example is built using the drilldown widget, this can be found in GitHub here. The Drilldown widget is built on top of the Esri Search widget and has all of the same properties and functionality of this widget. In addition it introduces a hierarchy of addresses allowing you to pinpoint the exact address you want to use.

Currently the Drilldown widget must connect to a LocatorHub 5.3 LLPG gazetteer. As the Drilldown widget is built on the Search widget creating it looks very similar with just a couple of differences. Just like the Search widget we wait for the map to load and then pass the map into the Drilldown widget.

    // Load the webmap
    var deferred = arcgisUtils.createMap("bea8606595d44ed5a8d82b3b22f6ca09", "map", {
        apOptions: {
            slider: true
        },
        usePopupManager: true,
        geometryServiceURL: "//sampleserver3.arcgisonline.com/ArcGIS/rest/services/Geometry/GeometryServer"
    });

Once the map has loaded we can create the Drilldown widget. First we create the locator using the LLPGLocator class that comes with the Drilldown code. Then we use this to set up a new source for the Drilldown widget, turn off suggestions as these are not supported by our locator and set some other standard Search properties.

    // Create the LLPG locator
    var llpgLocator = new LLPGLocator("//sunnyshire.esriuk.com/locatorhub/arcgis/rest/services/SunnyshireLLPGcopy/ADDRESS/GeocodeServer/");

    // Create the Drilldown widget
    var drillDown = new Drilldown({
        sources: [{
            locator: llpgLocator,
            singleLineFieldName: "SingleLine",
            outFields: ["*"],
            name: "LLPG LocatorHub",
            maxResults: 2000,
            placeholder: "Edinburgh addresses only"
        }],
        enableSuggestions: false,
        enableSourcesMenu: true,
        enableLabel: false,
        enableHighlight: true,
        autoNavigate: true,
        map: response.map
    }, "search");

    drillDown.startup();

The Web AppBuilder Drilldown widget can be found in GitHub here. The WAB Drilldown widget takes he Drilldown Widget and wraps it up to allow it to work with the Web AppBuilder.

To use any custom widget with the Web AppBuilder you need to have the developer version of the Builder hosted in your own environment. Full details of the Web AppBuilder and instructions on setting it up can be found here.

To use the widget download this repository and copy the Drilldown folder into the Web AppBuilder widget repository, by default this is client\stemapp\widgets. Then to get it to show in the applications you need to modify the config files and replace the Search widget with the Drilldown widget. The config files for the applications can be found in client\stemapp\predefined-apps As an example you can add the widget to the default viewer by changing Search to Drilldown as shown below.

{
    "uri": "widgets/Drilldown/Widget",
    "position": {
        "left": 55,
        "top": 5
    },
    "version": "1.3"
}