The GeocodeResourceManager control allows a developer to add, remove,
and set properties for any data source that provides geocoding
capabilities. ArcGIS Server, ArcIMS, Microsoft Virtual Earth and
ArcWeb data sources can be utilized. The FindAddressTask
control is designed to use the resources provided by the GeocodeResourceManager
to geocode address or variable (e.g. place name or
landmark) inputs. In addition, the IGeocodeResource and
IGeocodeFunctionality interfaces in the Common API enable a developer to
work with a geocode service programmatically.
Add the control to the page
Open or create a Web site within Visual Studio.NET.
Open a Web form in design mode, select the Toolbox, and expand the
ArcGIS Web Controls tab. Drag and drop a GeocodeResourceManager
on the Web form. You should see the following in Visual Studio.NET:
Note that the GeocodeResourceManager is only visible at design-time.
Add a resource item
To add geocode resources for use within your Web application, activate the
control, open or navigate to the Properties window, and click the ellipsis next
property. A resource collection editor dialog should be displayed.
On the GeocodeResourceItem Collection Editor dialog, click the Add
button to add a data source as a geocode resource to the
GeocodeResourceManager control. A GeocodeResourceItem is added
to the collection. This item provides properties to modify the behavior
of the resource, such as minimum candidate score, minimum match score, and
whether to return just match candidates or all candidates.
Candidate and match scores for an address are determined by the geocode
service, not the Web ADF. Each data source utilizes different,
although related, methods for managing geocode parameters to
The following properties can be modified for a geocode resource item
in the collection editor dialog:
property is used to uniquely identify the resource within the web
application. It is highly recommended to set the resource name to a
descriptive value in your application.
is a value between 0-100. When a geocode service searches for likely
candidates in the reference data, it uses this threshold to filter the results
provided. Locations that yield a score lower than this threshold are not
returned. If the geocode service seems unable to find any
candidates for an address that you want to geocode, you can lower this setting
so candidates with lower scores are returned. By default, this value is
set to the value defined by the service.
MinMatchScore is a value between 0-100. The minimum match score
lets you control how closely addresses have to match their most likely
candidate in the reference data to be considered a match for the address. A
perfect match yields a score of 100. A match score between 80 and 99 can
generally be considered a good match. An address below the minimum match
score is considered to have no match, but may still be a candidate depending on
value. By default, this value is defined by the service. If your
application demands that addresses be located with a high level of confidence,
you should set a higher minimum match score. If you want to maximize the number
of addresses that can be matched and don't mind if some addresses are
potentially matched incorrectly, you can use a lower setting.
ShowAllCandidates can be true or false. If true, all candidates
which have a score greater than the MinCandidateScore are
returned. If false, only candidates with a score greater than the MinMatchScore
are returned. By default, the value is false.
On the GeocodeResourceItem
Collection Editor dialog, the Definition property provides a set
of dialogs to connect to a data source provider and create a geocode
Click the ellipsis (...)
for the Definition property to open the Resource Definition
Editor. Select the Type of data source and define the
appropriate properties (see dialogs below). The Data Source property may be a url to an ArcGIS Server service
catalog or local machine name and optional connection port. Some data
sources support authentication. The Identity property enables
you to define the appropriate runtime credentials to connect to the data
source and utilize the resource. The Resource property defines
the geocode service to use when working with the resource.
The format of each property string is defined by the type of data
The following data source types are available:
Connecting to an
Server Local data source requires the machine name (connection host) on
which the Server Object Manager is running. The Additional GIS
Servers button enables configuring a fail-over or round-robin connection
for the resource. See Using the
Connection Library section for more details.
Once the data source is defined, the Resource property opens the ArcGIS
Resource Definition Editor dialog which provides a list of
available geocode services.
Note that the Identity property is grayed out and cannot be set from the
Resource Definition Editor dialog. At design-time, the identity of
the user running Visual Studio is used to connect to an ArcGIS Server local
data source. At runtime, that identity is established by the Web
application. Only one identity can be used to define access to all ArcGIS
Server local data sources in a single Web application. This identity can be explicitly
defined when building the Web ADF application in Visual Studio by
right-clicking the Web project in Solution Explorer, and selecting the
Add ArcGIS Identity option. Enter
the identity credentials that will be used to access ArcGIS Server
local resources at runtime. This information will be added to the
web.config file within a standard ASP.NET identity tag. If the
"Encrypt identity in web.config" checkbox is checked, the identity tag will be
encrypted, otherwise the username and password will be stored as clear
ArcGIS Server Internet
Server Web Services require entering the partial URL to the ArcGIS
Manager collection of services. This URL includes the Web server host
name, ArcGIS instance, and "services" folder name. This general URL provides
a list of ArcGIS Server Web Services to choose from.
authentication is enabled for an ArcGIS Server Web service, you must provide a username
and password to gain access to the Web services. ArcGIS Server Web
services are designed to use Basic authentication, therefore username and password
are Base64 encoded and included in the HTTP request to the Web server.
Since this is inherently insecure, confirm that your Web
site provides a secure channel for communication - namely it
has enabled SSL encryption accessible via HTTPS. This will
sufficiently encrypt the transmission of identity credentials
for Basic authentication.
Once the data source and identity are entered,
the Resource property provides a list of available geocode services.
The identity determines which services are available. If no identity is
specified, the remote Web server is responsible for assigning an identity,
often an anonymous user account.
ArcIMS has two options for connecting to
TCP : If the Web ADF
application has direct access to the ArcIMS Application Server, you can
create a TCP connection. Specify the hostname of the machine on
which the ArcIMS Application Server is running and the connection
port (default 5300). TCP connections do not use authentication, therefore
the Identity credentials are not used.
HTTP: If the Web ADF application has
access to a Web server that exposes the ArcIMS Servlet Connector you
can create an HTTP connection. Specify the Web server
hostname and the Web ADF will discover if an appropriate endpoint
is available. You can also specify a full path to the
endpoint. By default, the
Servlet Connector path is
. If authentication has been enabled,
enter the appropriate information in the ArcIMS Identity Editor
Additional IMS Servers button enables configuring a fail-over
or round-robin connection for the resource. See
Using the Connection Library for more details.
Once the connection properties have been set, use the
Resource Definition Editor dialog to select an Image Service that has geocoding enabled.
To enable geocoding on an ArcIMS Image Service, at least one layer in the
service must be configured for geocoding. For more information, see the
ArcXML Programmer's Reference Guide. Once the service is selected, pick
the layer in the service which will be utilized in the Web ADF as a
* Note, the ArcWeb service
data source has been deprecated in ArcGIS Server 9.3.1. This data
source will be removed in the next minor version release.
ArcWeb services provide location-based services that utilize a variety of data sources for
different regions of the world. The URL for
the ArcWeb Web service that provides geocode capabilities is preset and
cannot be changed. The Web service URL is:
A valid ArcWeb account must be specified
to connect to ArcWeb services. Once connected, the Resource
Definition Editor dialog allows you to browse any ArcWeb services
that provide geocoding services.
Microsoft Bing Maps (formerly known as Virtual Earth)
The Microsoft Live Services
SDK hosts a Bing Maps geocode Web
service for address and place matching. Bing Maps maintains
two service environments: staging and production.
The staging environment is designed to support development and testing
use of Bing Maps services; they are free of charge. The
production environment offers optimized services designed to
support deployed applications; it requires a license
fee. In either case, you will need a Bing Maps account
id. See the Virtual Earth data source discussion for steps on how to get existing account information
or create an account.
When adding a Microsoft Virtual
Earth resource item, you must provide the account id and password in
the Identity Editor.
Since there is
only one Bing Maps geocode Web service, the Resource
Definition Editor only enables you to select between the staging and
production environments. If you have not recieved a license to
use the Bing Maps production environment, check the "Use staging
Specify buddy controls
To utilize the resources in the GeocodeResourceManager, add a
FindAddressTask control. The FindAddressTask task control can only work
with one geocode resource at a time. You can also utilize geocode
resources programmatically via geocode
functionalities. Composite geocoding is
also possible using the Web ADF, but it requires
custom programming. Composite geocoding combines and
utilizes a set of geocoding services for a single address
matching process. The geocoding services are assigned a priority where if
the first service (highest priority) does not provide an adequate
match, the next service is used. The process continues until a successful
match is returned or all geocode services are unable return a
The following table provides a list of properties of
interest. For complete reference information, see the
GeocodeResourceManager control in the library reference section.
||The GeocodeResourceItem collection managed by this control.
Initialize a geocode resource programmatically
A geocode resource will be initialized for you if working with a
FindAddress task control. However, if you are working with a geocode
resource outside of the FindAddress task you may need to initialize
it before it can be used. The same situation applies when
creating a GeocodeResourceManager and adding geocode resources
dynamically at runtime. Specifically, the GeocodeResource needs
to be initialized. The resource manager is responsible for
managing the data source connection, thus server context creation and disposal
are managed for you. The following example illustrates how
to retrieve a geocode resource item from a GeocodeResourceManager,
initialize the resource and create a geocode functionality to use for
address matching operations.
GeocodeResourceItem geocodeResourceItem = GeocodeResourceManager1.ResourceItems.Find("Geocode Resource");
// Create a Web ADF Common API geocode functionality
IGeocodeFunctionality commonGeocodeFunctionality = (IGeocodeFunctionality)