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.

Before we get started, make sure that you have installed the ThinkGeo Product Center and that you have either started an evaluation or activated a full license of the following products:

• Map Suite Geocoder
• Map Suite Desktop Edition

While the Map Suite Geocoder component takes care of the business of geocoding and reverse geocoding data, in order to display it on an interactive map you need to use a control like Map Suite Desktop Edition.

If you installed the ThinkGeo Product Center in the default location, your Map Suite Geocoder 9.0 assemblies will be located in C:\Program Files (x86)\ThinkGeo\Map Suite 9.0\Map Suite Geocoder.

Download Sample Code From GitHub

Let's start with a new Windows Forms project in Microsoft Visual Studio (2012 or newer) and call it “HelloWorld” (see Figure 1). We can create the project with .NET Framework 4.0 or 4.5.

Figure 1. Creating a new project in Microsoft Visual Studio.

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

Note: Although it is not a ThinkGeo assembly, you also need to add “WindowsBase.dll” to the references. WindowsBase can be found on the .NET tab of the Add Reference dialog. If you don't do this, you will get the following error when you compile the project: “The type 'System.Collections.Specialized.INotifyCollectionChanged' is defined in an assembly that is not referenced. You must add a reference to assembly 'WindowsBase, Version=4.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35'.”

1. When you first open Microsoft Visual Studio 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 (x86)\ThinkGeo\Map Suite 9.0\Map Suite Geocoder\Current Version\Managed Assemblies folder and select the “DesktopEdition.dll” file.

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

Figure 2. The Map Controls under 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 (x86)\ThinkGeo\Map Suite 9.0\Map Suite Geocoder\Current Version\Managed Assemblies 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.

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 (x86)\ThinkGeo\Map Suite 9.0\Map Suite Geocoder\Current Version\Managed Assemblies folder and select “MapSuiteGeocoder.dll”.

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

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 (x86)\ThinkGeo\Map Suite 9.0\Map Suite GeoCoder\Sample Templates\AddressLocator_Desktop\AddressLocator_Desktop\App_Data", 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, build and run the sample. Because our sample data set only contains street data for Chicago, IL, to perform a test you will need to enter an address in Chicago and then click the button to locate it. Once you do, 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.

You now know the basics of using Map Suite Geocoder 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 various parts of the Map Suite Geocoder work together:

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