Geocoding

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 will be displayed on a map.    

ArcIMS Image and Feature services can provide geocoding capabilities.  ArcMap services do not support geocoding.  To enable geocoding in an ArcIMS service, see the section titled "Setting geocoding properties" in the online ArcIMS help system.  Geocode functionality in the ArcIMS API is only designed to work with ArcIMS Image services.   

The ESRI.ArcGIS.ADF.IMS.Geocode namespace contains the primary classes used to consume geocoding functionality in an ArcIMS service: Geocoder, InputFieldCollection, InputField, AddressValueCollection and AddressValue.  The following steps outline a typical geocode process:

1. Return the Geocoder instance from a FeatureLayer with geocoding enabled in an ArcIMS service.
2. Get the input fields expected by the geocode process.  Use the properties of the InputField objects within the Geocoder's InputFieldCollection
3. Create an AddressValueCollection to store AddressValue objects for each input field.  The value of each AddressValue object will reference the user-provided address to be geocoded.
4. Call the Geocode method on the Geocoder instance and pass the AddressValueCollection containing 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 within an ArcIMS service to create a Geocoder instance.  Typically, a Layer is retrieved from a MapView's LayerCollection and cast to FeatureLayer.   The Geocoder instance is created by getting the read-only Geocoder property on the FeatureLayer.

LayerCollection MyLayerCollection = MyMapView.Layers;
FeatureLayer MyFeatureLayer = (FeatureLayer) MyLayerCollection.FindByName("streets");
Geocoder MyGeocoder = MyFeatureLayer.Geocoder;

Each Geocoder is associated with an address style defined within the feature layer in the ArcIMS service.  The address style dictates the input fields required by the ArcIMS geocoding engine to process a user-defined address.  For example, the ArcIMS address style "US Address with Zone" defines three input fields: STREET, ZONE, and CROSSSTREET.  The Geocoder's 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 a new 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's Geocode method, to return a FeatureTable.

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 three columns of type System.Data.DataColumn: SCORE, ADDRESSFOUND, and #SHAPE#.  The SCORE field contains an integer value between 0 and 100 to reflect 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.  The ADDRESSFOUND field returns matched address information for a candidate.  The field contents are defined by the OUTPUT tag in an ArcIMS address style (*.stl) and may reference information in both the user-defined address and geocode layer data.  The #SHAPE# field 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.

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 a new AcetateLayer or retrieve an existing one.
2. Get the AcetateElementCollection via the AcetateLayer.AcetateElements property.
3. Create a new 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 in the map.  Set the Symbol property on the GeometryElement to the new marker symbol.
6. Add the GeometryElement object to the AcetateElementCollection of the AcetateLayer. 
7. Add the AcetateLayer to the map via the MapView's LayerCollection. 
8. Redraw the MapView and retrieve the new map image.
   

This code sample illustrates how to add a Point to an acetate layer in a MapView.

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;