Geocoding Services

Geocoding services ("geocoders") convert between addresses and spatial data. Converting an address to spatial data enables the address to be shown on the map. This is called "forward geocoding". Converting from spatial data (a geographic location) to an address is called "reverse geocoding".

In order for a site's viewers to do operations that involve geocoding, you must configure at least one geocoding service in the site. Essentials supports unsecured and secured ArcGIS geocoding services, and the Bing Maps geocoding service.

About Configuration Settings for Geocoding Services

After you have added a geocoding service to a site, you might need to configure additional settings. This depends on what type of viewer you are using and which geocoding-dependent features you configure.

Additional geocoding service settings (other settings are omitted)

The settings are summarized in the table below. In the table, the geocoding service settings are identified by number. The numbers relate to the screen capture above.

To use the table, first look in the Feature column to find the feature that you want to configure. Now read across the row for that feature to find out which settings to configure. In addition to configuring the geocoding settings, you must configure the feature itself. Follow the link given in the Feature column to configure the feature.

The table uses the following values:

• Yes: You must configure the settings that say Yes for that feature.

• Optional: Settings that are Optional allow you to configure optional aspects of that feature. You do not need to configure Optional settings.

• No Effect: If you configure a setting that has No effect, the setting will not have any effect on the feature (it might affect other features, if you configure more than one of the features listed in the table). For example, configuring a Display Name for Global Search has no effect. You do not need to configure settings that have no effect, but there is no harm if you do.

For information about what the individual settings do, see Configuration Settings for ArcGIS Geocoding Services and Configuration Settings for the Bing Maps Geocoding Service .

Geocoding Service Settings to Configure Geocoding Features

Feature
Global Search (text search) See Search.	Yes	Yes	No effect	Optional	No effect	No effect
Batch Geocoding See Configure a Batch Geocoder.	No effect	No effect	No effect	Optional	No effect	No effect

ArcGIS Geocoding Services

If you are using the HTML5 Viewer with a proxy page, you must register the geocoding service with the proxy. The enables the proxy to forward requests to the geocoding service. For instructions, see Set Up a Proxy Page.

Add an ArcGIS Geocoding Service

To add an ArcGIS geocoding service to a site:

1. In Manager, edit the site that you want to configure, and then click GIS Services from the side panel.

2. On the Geocoding tab, click Add Geocoding Service.

   The Geocoding Service Wizard opens.

3. With ArcGIS Geocoding Service selected, click Next.

4. Type a Display Name for the geocoding service.

   Choose a display name that end users understand.

5. Click Next.

6. Type in the URL of the ArcGIS REST services endpoint. By default, this is:

   http://[server.domain.com]/ArcGIS/rest/services

   where [server.domain.com] is the fully qualified host where the service is located.

   Essentials supports the ArcGIS Online World Geocoding Service. The URL is:

   http://geocode.arcgis.com/arcgis/rest/services/World/GeocodeServer

7. Click Next.

   Manager discovers the geocoding services at the specified URL.

8. Click Finish.

   The wizard closes and the Edit Geocoding Service page for the new geocoding service opens.

9. Click Save Site.

Configuration Settings for ArcGIS Geocoding Services

ArcGIS geocoding services have the following settings:

• Service Type: (for information only) The service type is ArcGISGeocoder.

• Display Name: The name that is used to refer to this geocoding service.

  Choose a display name that end users understand.

• Service URL: The geocoding service's URL. Features that use this geocoding service send geocode requests to this URL.

• Default Batch Geocoder: Makes this geocoder the default for batch geocoding. This setting only applies to one geocoder at any time.

• Default Reverse Geocoder: Makes this geocoder the default for reverse geocoding. Reverse geocoding is the process of determining the address of a given map point. This setting only applies to one geocoder at any time.

• Icon URI: Configures a custom icon for this geocoding service.

• Feature Zoom Scale: The scale to zoom to when clicking a geocoding result.

• Authentication Settings: If the geocoding service is secured, select the authentication method for Essentials to use when connecting to the service.

  • Web Tier (default or anonymous credentials): Select this option if:

    • The service is secured using Integrated Windows Authentication and you want Essentials to authenticate as the application pool user.

      or

    • The service is not secured.

  • Web Tier (configured credentials): Select this option if:

    • The service is secured using basic or digest authentication.

      or

    • The service is secured using Integrated Windows Authentication and you want to configure the credentials for Essentials to use when authenticating.

    In the Username and Password text fields, enter the credentials that you want Essentials to use.

  • Token Security (by user): Select this option if the service is secured using token security.

    In the Username and Password boxes, type the credentials that you want Essentials to use when authenticating. If you have changed the location where tokens are issued, type the URL of the location in the Token URL box.

    By default, Essentials assumes the token duration of all your ArcGIS services is 60 minutes, which is the ArcGIS default. However, if the token duration of any of your ArcGIS services is shorter, you must specify the token duration in Essentials. To specify the token duration:

    1. Open the Essentials web.config file.

       The Essentials web.config file is located in {GE_HOME}\REST\Web.config.

    2. In the appSettings element, add a new add element.

    3. Add a key attribute to appSettings and set it to ArcGisRestMapServiceBase.MaximumTokenDuration.

    4. Add a value attribute to appSettings and set it to the maximum token duration in minutes.

    For example, to set the maximum token duration to 20 minutes: 

      <add key="ArcGisRestMapServiceBase.MaximumTokenDuration" value="20" />.

  • Token Security (explicit tokens): In the Server Token box, type or paste the long-lived server token that Essentials will use to authenticate. You can also optionally configure a long-lived client token.

    Select this option if the service is secured using token security and you want to use long-lived tokens. This method stores the token(s) in the site.

• Include in Global Search: When this checkbox is selected, the geocoding service can be searched in Global Search operations.

• Global Search Key: The geocode service field to use when a value is entered in Global Search. The default is SingleLine. This setting is only available when the Include in Global Search checkbox is selected. Note that when the global search key is SingleLine, parameters configured for the Geocoding Service are ignored when sending Global Search queries. To use additional parameters, select a global search key other than SingleLine.

• Parameters: Use this table to configure the geocoding service to be used by features that perform forward geocoding.

  • Parameter: (for information only) The geocoding service's Address Fields.

  • Display Name: (used by Address Search) The label to display beside the box where the user enters the value for this parameter. For example, if the geocoding service has a Zip field, you could set the display name to "Zip/Postal Code".

  • Value: An optional setting used by Global Search, Address Search, and Batch Geocoding. The value to search for (Global Search) or to use in geocoding (Address Search, Batch Geocoding). HTML5 viewers only use Value if the end user does not specify a value. Legacy Silverlight viewers only use Value if the Required checkbox is selected and the end user does not specify a value.

  • Required (Silverlight viewers only): When this checkbox is selected, the parameter must have a value before an Address Search or Batch Geocode can be done. The value can either come from the configuration (the parameter's Value setting) or from the end user. If the end user specifies a value, it overrides the value that is configured in the site. This setting is optional.

  • Visible: When this checkbox is selected, the Address Search panel has a text box for the user to enter a value.

See also...

About Configuration Settings for Geocoding Services

Configure an ArcGIS Geocoding Service

When you add an ArcGIS geocoding service to a site, the wizard prompts you to configure the Display Name and Service URL settings. Instructions for changing the Display Name and URL are given below.

Depending on which features you configure that use the geocoding service, you might need to configure additional settings after the wizard has completed. For information about which settings to configure, see About Configuration Settings for Geocoding Services.

Additional settings for ArcGIS geocoding services

To configure an ArcGIS geocoding service:

1. In Manager, edit the site that you want to configure, and then click GIS Services from the side panel.

2. On the Geocoding tab, click the Edit icon beside the geocoding service that you want to edit.

3. In the Display Name box, change the geocoding service's name if you want.

   Choose a display name that end users understand.

4. In the Service URL box, change the geocoding service's URL if you want. Use a fully qualified URL.

   If you use a proxy page, update the geocoding service's URL in the proxy.config file.

   Manager will connect to the URL. If the geocoding service's Address Fields are different than the Address Fields at the previous URL, Manager highlights the fields that do not exist at the current URL. You can remove the highlighted fields by clicking the Remove icon beside each field.

   

   Fields that are not present at the updated URL are highlighted

5. If you want to make this geocoder the default for batch geocoding, select Default Batch Geocoder. This setting only applies to one geocoder at any time.

6. If you want to make this geocoder the default for reverse geocoding, select Default Reverse Geocoder. Reverse geocoding is the process of determining the address of a given map point. This setting only applies to one geocoder at any time.

7. Select an Authentication Method to access the geocoder.

8. If you want to use this geocoding service in Global Search, select the Include in Global Search checkbox and then select the attribute to search on from the Global Search Key drop-down list.

9. Fill in the desired search parameters in the table.

   For detailed information about the settings on the Edit Geocoding Service page, see About Configuration Settings for Geocoding Services.

10. Click Apply Changes.

The Bing Maps Geocoding Service

If you are using the HTML5 Viewer with a proxy page, you must register the geocoding service with the proxy. The enables the proxy to forward requests to the geocoding service. For instructions, see Set Up a Proxy Page.

Add a Bing Maps Geocoding Service

To add a Bing Maps geocoding service to a site:

1. In Manager, edit the site that you want to configure, and then click GIS Services from the side panel.

2. On the Geocoding tab, click Add Geocoding Service.

   The Geocoding Service Wizard opens.

3. Select Bing Geocoding Service, and then Next.

4. Type a Display Name for the geocoding service.

   Choose a display name that end users understand.

5. Click Next.

6. Enter your Bing Maps key in the Bing Maps Key text field.

   To obtain a key or to learn more about Bing Maps, see Getting a Bing Maps Key in the Microsoft documentation.

7. Click Finish.

   Manager validates the Bing Maps Key. If it returns as invalid, re-enter the key. The geocoding service is not be added to the site if the key is not valid.

   When the key validates, the wizard closes and the Edit Geocoding Service page opens.

Configuration Settings for the Bing Maps Geocoding Service

The Bing Maps geocoding service has the following settings:

• Service Type: (for information only) The service type is BingGeocoder.

• Display Name: The display name that is used to refer to this geocoding service. Choose a display name that end users understand.

• Service URL: The URL for the Bing Maps geocoding service. If you leave this setting blank, the URL for the public Bing Maps geocoding service over HTTP is used.

• Bing Maps Key: Your Bing Maps Key.

• Culture: The culture to use to translate and prioritize the results.

• Include in Global Search: When this checkbox is selected, the geocoding service can be searched in Global Search operations.

• Global Search Key (Silverlight viewers only): The attribute to search in Global Search. This setting is only available when the Include in Global Search checkbox is selected.

• Parameters Table (Silverlight viewers only): Use this table to configure the geocoding service to be used by features that perform forward geocoding.

  • Parameter: (for information only) The geocoding service's Address Fields.

  • Display Name: (used by the Address Search Tool) The label to display beside the box where the user enters the value for that parameter. For example, if the geocoding service has a Zip field, you could set the display name to "Zip/Postal Code".

  • Value: (used by Global Search and Address Search) (optional) The value to search for (Global Search) or to use in geocoding (Address Search).

  • Required: (used by Address Search) (optional) When this checkbox is selected, the parameter must have a value before an Address Search can be done. The value can either come from the configuration (the parameter's Value setting) or from the user.

  • Visible: (used by Address Search) When this checkbox is selected, the Address Search panel has a text box for the user to enter a value.

See also...

About Configuration Settings for Geocoding Services

Configure a Bing Maps Geocoding Service

When you add a Bing Maps geocoding service to a site, the wizard prompts you to configure a display name and specify the Bing Maps Key.

You can also set a culture to attach to geocoding requests. The Bing Maps geocoding service uses the culture to translate and prioritize the results it returns. For information, refer to the Microsoft documentation on the Culture Parameter.

Instructions on configuring the display name, service URL, key, and culture are given below.

Depending on which features you configure that use the geocoding service, you might need to configure additional settings.

Additional settings for the Bing Maps geocoding service

The HTML5 Viewer only uses geocoding services for Global Search. To enable Global Search, add a geocoding service to your site. No additional configuration is required.

To configure the Bing Maps geocoding service:

1. In Manager, edit the site that you want to configure, and then click GIS Services from the side panel.

2. On the Geocoding tab, click the Edit icon beside the geocoding service that you want to configure.

3. In the Display Name box, change the geocoding service's name if you want.

   Choose a display name that end users understand.

4. In the Service URL box, type or paste the URL for the Bing Maps geocoding service that you are using.

   You only need to configure the URL if you are hosting the Bing Maps geocoding service, or you want to enforce the use of SSL with the public Bing Maps service.

5. If you want to use this geocoding service in Global Search, select the Include in Global Search checkbox.

   and then select the attribute to search on from the Global Search Key drop-down list.

6. In the Bing Maps Key box, change the key if you want.

   Manager will verify the key when you apply the changes.

7. Enter a culture code if you want.

   For information, refer to the Microsoft documentation on Supported Culture Codes.

8. Browse for an Icon URI to configure a custom icon for the geocoding service if you want.

   The HTML5 Viewer does not use the remaining settings.

9. Click Apply Changes.

Remove a Geocoding Service

If you use a proxy page, you may want to remove the geocoding service from the proxy.config file after you have removed it form the site.

To remove a geocoding service:

1. In Manager, edit the site that you want to configure, and then click GIS Services from the side panel.

2. On the Geocoding tab, click the Remove icon next to the geocoding service that you want to delete.

   You are prompted to confirm the deletion.

3. Click OK.

Troubleshooting Geocoders

Limit the Geographic Area

Some geocoding services may not be able to find addresses unless you specify the geographic area to geocode within. If you find that features that do forward geocoding do not return the results you expect, try configuring the Value setting for one or more parameters.

The Configuring Value settings for a geocoding service's parameters affects all the configured features that use this service to do forward geocoding—the values are sent to the geocoding service as part of the geocoding request.

To specify the geographic area for forward geocoding:

1. In Manager, edit the site that you want to configure, and then click GIS Services from the side panel.

2. On the Geocoding tab, click the Edit icon next to the geocoding service that you want to configure.

3. Enter values for one or more of the parameters in the parameter's Value text field.

   For example, in the screen capture below, the City and State are specified.

   

   Specify the area to geocode within

4. Click Apply Changes.

Use the Geocoding Service's Fully Qualified URL

Make sure you have configured the geocoding service's fully qualified URL. To check, edit the geocoding service's Service URL text field. Note that the Service URL box is blank for public Bing Maps geocoding services. In this case, Essentials provides the URL.

Register the Geocoding Service with an HTML5 Viewer Proxy Page

If you are using the HTML5 Viewer with a proxy page, you must register the geocoding service with the proxy. The enables the proxy to forward requests to the geocoding service. For instructions, see Set Up a Proxy Page.