Welcome to Map Suite Geocoder from ThinkGeo, a full-featured library that makes it easy for any .NET developers to add geocoding functionality to a Microsoft .NET application quickly and easily. Using the intuitive object model, even developers inexperienced in spatial reference can have a fully-featured geocoder working in minutes.

The Map Suite Geocoder provides a very flexible mechanism to match tabular data that contains location information (such as street addresses) with real-world coordinates using a MatchingPlugIn. With different MatchingPlugIns, you can match any kind of data that you want. And by combing PlugIns together, you can accomplish very complex geocoding applications with ease.

The purpose of this guide is to help you get started quickly to build your own geocoding applications. Like any new software, there is some learning to be done.

How do we start to learn how to take advantage of Map Suite Geocoder? The best way is to make a sample application with it.

Setting up the Environment

Let's start with a Windows Forms project in the Visual Studio 2008 IDE and call it "Hello World" (see Figure 1). We will create the project with .NET Framework 3.5.

Figure 1. Creating a new project in the Visual Studio 2008 IDE.

The project "HelloWorld" is created in a new solution that is also called "HelloWorld". The wizard creates a single Windows Form.

Adding the Map Control to the Visual Studio .NET IDE Toolbox

1. When you first open the Visual Studio 2008 IDE after installing Map Suite, you may not see the Map Suite Desktop Edition's map control in the Toolbox. In this case, you will need to perform the following steps to add it.

Hover on the Toolbox and right click anywhere on the list of controls. You will get a pop-up menu. Select "Choose items..."

2. The Choose Toolbox Items dialogue will appear. You will need to select the ".NET Framework Components" tab and then click the "Browse..." button. Finally, navigate to the "C:\Program Files\ThinkGeo\Map Suite Geocoder Evaluation Edition 4.0\HowDoISamples\CSharp HowDoISamples\CSharp Desktop HowDoISamples\bin" folder and select the DesktopEdition.dll.

3. You should now have the Map control available in your Toolbox as shown in the following figure.

Figure 2. The Desktop Edition's Map Control in the Toolbox window.

Draw the Map control on the form by clicking on the Map control in the Toolbox and then drag and drop (using the left mouse button) to the size your desire. For this sample, you can leave the name of Map control as winformMap1 so our map will display in it.

4. We need to add MapSuiteCore.dll to the reference. Right-click the project in Solution Explorer and select "Add Reference...", navigate to the "C:\Program Files\ThinkGeo\Map Suite Geocoder Evaluation Edition 4.0\HowDoISamples\CSharp HowDoISamples\CSharp Desktop HowDoISamples\bin" folder and select MapSuiteCore.dll.

5. Add a Textbox, a Button and a ListBox to the form.

Figure 3. Your project workspace with form controls in place.

Adding Geocoder Reference to the "Hello World" Sample

Next, we need to add MapSuiteGeocoder.dll to the reference. Right-click the project in Solution Explorer and select "Add Reference..." Next, navigate to the "C:\Program Files\ThinkGeo\Map Suite Geocoder Evaluation Edition 4.0\Developer References\MapSuite Geocoder" folder and select MapSuiteGeocoder.dll.

Now we have our MapSuiteGeocoder.dll referenced and necessary controls added, we are ready to add the code.

Map Suite Geocoder "Hello World" Sample

After this section, you will be able to geocode using your own data. At the very beginning, let's have a look at the important classes we will use:

Geocoder

Geocoder is the generic facade class for geocoding. UsaGeocoder is the specific class for United States-based geocoding. There is a MatchingPlugIn collection in the Geocoder class so you can add your own MatchingPlugIn objects to accomplish custom matching requirements.

GeocoderMatch Collection

GeocoderMatch Collection represents the match result of Geocoder which contains the collection of GeocoderMatch. GeocoderMatch has a Dictionary property named NameValuePairs that contains the key-value based match results.

"Hello World" Sample

In creating our "Hello World" sample, our first step is to set references to the MapSuiteGeocoder workspace at the very top of our code. Setting a reference to the MapSuiteGeocoder workspace can be done in the "code-behind" of the Form by selecting the Form and pressing the F7 function key. To display the Geocoder results on the map with the MapSuite Desktop Edition, we also need four additional references. You can set all of these references like this:

using ThinkGeo.MapSuite.MapSuiteGeocoder;
using ThinkGeo.MapSuite.DesktopEdition;
using ThinkGeo.MapSuite.Core;
using System.Collections.ObjectModel;

Before we start looking at the Geocoder code, we need to add some code to display the map. We will add this code in the Form Load event handler as follows:

private void Form1_Load(object sender, EventArgs e)
    {
        // Setting up the map unit and set the Chicago extent
        winformsMap1.MapUnit = GeographyUnit.DecimalDegree;
        winformsMap1.CurrentExtent = new RectangleShape(-125, 50, -66, 23);

        // Create the overlay and add it to the map
        LayerOverlay mainOverlay = new LayerOverlay();
        winformsMap1.Overlays.Add("mainOverlay", mainOverlay);

        // Setup the World Map Kit WMS Overlay
        WorldMapKitWmsDesktopOverlay worldMapKitOverlay = new WorldMapKitWmsDesktopOverlay();
        winformsMap1.Overlays.Add("WorldMapKitOverlay", worldMapKitOverlay);

        // Setup the marker overlay and add it to the map            
        LayerOverlay markerOverlay = new LayerOverlay();
        winformsMap1.Overlays.Add("MarkerOverlay", markerOverlay);

        // Setup the marker layer
        InMemoryFeatureLayer markerLayer = new InMemoryFeatureLayer();
        markerLayer.ZoomLevelSet.ZoomLevel01.ApplyUntilZoomLevel = ApplyUntilZoomLevel.Level20;
        markerLayer.ZoomLevelSet.ZoomLevel01.DefaultPointStyle = PointStyles.CreateSimplePointStyle(PointSymbolType.Circle, GeoColor.SimpleColors.Red, 10);
        markerOverlay.Layers.Add("MarkerLayer", markerLayer);            

        winformsMap1.Refresh();
    }

Now let's look at some sample code that will bring these concepts to fruition. In this code, we'll accomplish the following:

1. Add a click event handler for the Button.
2. Create a UsaGeocoder object and pass the index data path to the constructor.
3. Call the Open method.
4. Call the Match method to get the MatchResult object.
5. Finally, call the Close method to close.

// Get the path to the data files and create the Geocoder
    UsaGeocoder usaGeocoder = new UsaGeocoder(@"C:\Program Files\ThinkGeo\Map Suite Geocoder Evaluation Edition 4.0\HowDoISamples\SampleData\ChicagoData", MatchMode.FuzzyMatch);

    // Open the geocoder, get any matches and close it
    Collection<GeocoderMatch> geocoderMatches;
    try
    {
        usaGeocoder.Open();
        geocoderMatches = usaGeocoder.Match(textBox1.Text);
    }
    finally
    {
        usaGeocoder.Close();
    } 

You can get results in detail by looping through geocoderMatches and displaying them on the map.

InMemoryFeatureLayer markerLayer = winformsMap1.FindFeatureLayer("MarkerLayer") as InMemoryFeatureLayer;
    if (geocoderMatches.Count > 0)
    {
        listBox1.Items.Clear();
        listBox1.Items.Add(geocoderMatches[0].ToString());
        PointShape pointShape = new PointShape(geocoderMatches[0].NameValuePairs["CentroidPoint"]);
        winformsMap1.Overlays["MarkerOverlay"].Lock.EnterWriteLock();
        try
        {
            markerLayer.EditTools.BeginTransaction();
            markerLayer.EditTools.Add(new Feature(pointShape));
            markerLayer.EditTools.CommitTransaction();
        }
        finally
        {
            winformsMap1.Overlays["MarkerOverlay"].Lock.ExitWriteLock();
        }
        winformsMap1.CurrentExtent = new RectangleShape(geocoderMatches[0].NameValuePairs["BoundingBox"]);
        winformsMap1.Refresh();
    }

Now, run the sample, enter an address in Chicago, IL (because here we only reference the Chicago data for geocoding) in the TextBox and click the button. Map Suite Geocoder will return a result on your map, similar to the following screenshot:

Figure 4. Your first geocoding application is up and running.

Summary

You now know the basics of using MapSuiteGeocoder and are able to get started adding functionality to your own applications. Let’s recap what we have learned about the object relationships and how the pieces of MapSuiteGeocoder work together:

1. There is a Open-Match-Close pattern in the Geocoder object;
2. The Geocoder returns a collection of GeocoderMatch that represents one matched result, and a GeocoderMatch object contains a key-value collection.

If you have questions about anything covered in this Quick Start Guide, the ThinkGeo Support Team is ready and available to help. If we can be of any assistance, please contact us using the below information:

Free Discussion Forums: ThinkGeo Discussion Forums
Pre-Sales & Customer Support: ThinkGeo Customer Portal
Support Phone: 1-866-847-7510
1-785-727-4133 (Outside North America)
Web Site: http://thinkgeo.com