Geocoding

Summary Geocoding is the process of identifying the coordinates of a location given its attribute information. Address matching, a type of geocoding, is a process that assigns a geographic location to an address by matching it to a street database. Each potential match (or candidate) is assigned a score to determine how closely the address matched information in the street database. Typically, the candidate with the best score is displayed on a map.

In this topic

About geocoding in the ArcIMS API

ArcIMS image and feature services provide geocoding capabilities. To enable geocoding in an ArcIMS service, see the Setting geocoding properties topic in the online ArcIMS help system. Geocoding functionality in the ArcIMS application programming interface (API) is designed to work with ArcIMS image services only. ArcMap services do not support geocoding.
The ESRI.ArcGIS.ADF.IMS.Geocode namespace contains the primary classes used to consume geocoding functionality in an ArcIMS service. These classes are as follows:
  • Geocoder
  • InputFieldCollection
  • InputField
  • AddressValueCollection
  • AddressValue
The following steps outline a typical geocode process in an ArcIMS image service:
  1. Return the Geocoder instance from a FeatureLayer with geocoding enabled.
  2. Get the input fields expected by the geocode process. Use the properties of the InputField objects in the Geocoder InputFieldCollection.
  3. Create an AddressValueCollection to store AddressValue objects for each input field. The value of each AddressValue object references the user-provided address to be geocoded.
  4. Call the Geocode method on the Geocoder instance and pass the AddressValueCollection containing the user-provided address values. A FeatureTable (namespace ESRI.ArcGIS.ADF.IMS.Carto.Layer) is returned containing each match candidate.
  5. Display the geocoded point of a candidate in a MapView.

Accessing address style input fields

Geocoding must be enabled on a feature layer in an ArcIMS service to create a Geocoder instance. Typically, a layer is retrieved from a MapView LayerCollection and cast to FeatureLayer. The Geocoder instance is created by getting the read-only Geocoder property on the FeatureLayer as shown in the following code:
[C#] 
LayerCollection MyLayerCollection = MyMapView.Layers;
FeatureLayer MyFeatureLayer = (FeatureLayer)MyLayerCollection.FindByName("streets");
Geocoder MyGeocoder = MyFeatureLayer.Geocoder;
Each Geocoder is associated with an address style defined in the feature layer in the ArcIMS service. The address style dictates the input fields that are required by the ArcIMS geocoding engine to process a user-defined address. For example, the ArcIMS address style US Address with Zone defines the following input fields:
  • Street
  • Zone
  • CrossStreet
The Geocoder InputFieldCollection contains an InputField for each input field in the address style. Each InputField maintains a set of properties to uniquely define the field.

Geocoding an address

Once you determine the address style input fields, you can create the classes containing a user-defined address. Create an AddressValueCollection instance and add one or more AddressValue objects to it. Each AddressValue constructor takes two arguments, the ID property of an InputField and the user-defined value for the input field. The address style dictates which input fields are required. For example, the ArcIMS address style US Address with Zone requires content in two fields: Street and Zone. After adding the AddressValue objects, pass the AddressValueCollection as an argument to the Geocoder Geocode method, to return a FeatureTable. This process is shown in the following code:
[C#] 
AddressValueCollection MyAVC = new AddressValueCollection();
AddressValue MyAddressValue1 = new AddressValue("STREET", MyTextBoxAddress.Text);
AddressValue MyAddressValue2 = new AddressValue("ZONE", MyTextBoxZone.Text);
MyAVC.Add(MyAddressValue1);
MyAVC.Add(MyAddressValue2);
FeatureTable MyFeatureTable = geocoder.Geocode(MyAVC);

Processing match candidates

The FeatureTable returned from a geocode process is a type of System.Data.DataTable, a standard ADO.NET data structure. The table contains the following columns of type System.Data.DataColumn:
  • Score—Contains an integer value between 0 and 100 that reflects how closely the data in a user-defined address and the geocode layer (e.g., streets database) match. A score equal to 100 is a perfect match. 
  • AddressFound—Returns matched address information for a candidate. The field contents are defined by the Output tag in an ArcIMS address style (*.stl) and can reference information in both the user-defined address and geocode layer data. 
  • #SHAPE#—Contains the geocoded location, in map units, as a Geometry object  (ESRI.ArcGIS.ADF.Web.Geometry namespace). Since the location is a single point, it can be cast to a Point object in the same namespace.
To iterate through the FeatureTable, you can use the Enumerator (System.Collections namespace) on the DataRowCollection to retrieve data values.
This process is shown in the following code:
[C#] 
IEnumerator MyEnumRows = MyFeatureTable.Rows.GetEnumerator();
while (MyEnumRows.MoveNext)
{
    DataRow MyDataRow = (DataRow)MyEnumRows.Current();
    int MyScore = (int)MyDataRow["SCORE"];
    string MyAddress = (string)MyDataRow["ADDRESSFOUND"];
    Point MyPoint = (Point)MyDataRow["#SHAPE#"];
}

Adding a geocoded point to a map

Once a match candidate has been selected, frequently the location of the address match needs to be displayed on a map.  In most cases, the location (or Point) will be added to a graphic to a map, also know in ArcIMS as an acetate layer.  The following steps outline the typical process for adding a graphic point to a map:
  1. Create an AcetateLayer or retrieve an existing one.
  2. Get the AcetateElementCollection via the AcetateLayer.AcetateElements property.
  3. Create a GeometryElement and specify the units of the element, either database or pixel.
  4. Set the Element property on the GeometryElement object to the geocoded point.
  5. Create a marker symbol (e.g., SimpleMarkerSymbol) to display the point on the map.
  6. Set the Symbol property on the GeometryElement to the new marker symbol.
  7. Add the GeometryElement object to the AcetateElementCollection of the AcetateLayer.
  8. Add the AcetateLayer to the map via the MapView LayerCollection.
  9. Redraw the MapView and retrieve the new map image.
The following code illustrates how to add a point to an acetate layer in a MapView:
[C#] 
AcetateLayer MyAcetateLayer = new AcetateLayer("myacetatename");
AcetateElementCollection MyAcetateElementCollection = MyAcetateLayer.AcetateElements;

GeometryElement MyGeometryElement = new GeometryElement(AcetateUnits.Database);
MyGeometryElement.Element = MyPoint;

SimpleMarkerSymbol MySimpleMarkerSymbol = new SimpleMarkerSymbol();
MySimpleMarkerSymbol.Color = System.Drawing.Color.Yellow;
MySimpleMarkerSymbol.Width = 16;

MyGeometryElement.Symbol = sms;
MyAcetateElementCollection.Add(MyGeometryElement);

MyMapView.Layers.Add(MyAcetateLayer);
MyMapView.Draw();
string MyUrl = MyMapView.Image.Url;