ThinkGeo Cloud
ThinkGeo UI Controls
ThinkGeo Open Source
Help and Support
External Resources
ThinkGeo Cloud
ThinkGeo UI Controls
ThinkGeo Open Source
Help and Support
External Resources
Note: The page was created before Map Suite 10. Map Suite 10.0 organized many classes into new namespaces and assemblies as well as had a few minor breaks in compatibility. The majority of previously built code should work without modification assuming the new namespaces are added. For guidance on upgrading your existing code, please check out MapSuite 10 Upgrade Guide.
The Map Suite Geocoder QuickStart Guide will guide you through the process of creating a simple geocoding application that works with United States-based addresses, and will help you become familiar with the Map Suite Geocoder. This edition of the QuickStart Guide supports Map Suite Geocoder 9.0.0.0 or higher, and shows you how to create a demonstrative Windows Forms application.
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:
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.
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:
UsaGeocoder
object and pass the index data path to the constructor. Open
method. Match
method to get the MatchResult
object. 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