This data map style should be used when you want to display only locations and have no data associated with them. For example, if you want to display your company’s retail store locations in the United States, use a location data map. In this data map style, there are two display options to represent locations on maps:

This data map style should be used when you have a single data item associated with each location that you want displayed on a map (or when you have multiple data items but want to display only one on the map). For example, to display the annual sales for each retail store in the United States, use a single-item data map. In a single item data map, each location has an associated data item. In this category, you have four display options:

Figure 3-4. Sized circle map

In all these map styles, there is only one dimension being analyzed based on location (for example, retail store sales). But what map styles would you use to display both your sales and your competitor’s sales based on location? This situation is when you need multiple item data maps .

In multiple item data maps, you display two or more items based on location. For example, you could display your sales and your competitor’s sales per state to understand how you are performing against your competitor, or you could display your sales and average spending per state to verify whether you are targeting the right market segments. So, in a multiple item data map, there are two or more pieces of information associated with each location. Again, in this category, there are different map styles that come to our rescue to represent multiple values for each location:

Figure 3-8. Column chart map (Color Plate 5)

Figure 3-9. Series column chart map

Now that we know what data map styles are and what they are well-suited for, let’s look at the DataSet.DisplayDataMap method used to display a data map.

This is the first step in displaying a data map. Choose the map style for the data map using the DataMapType argument. This argument is GeoDataMapType enumeration, and you can choose among the nine available map styles. Setting it to geoDataMapTypeDefault allows MapPoint 2004 to decide what map is best suited for the input data and other factors. In our example, we wanted a pie chart map, so set this to geoDataMapTypeUnsizedPie enumeration value.

The portion of the hypothetical display data map command completed so far:

Next, let’s look at the data specification arguments category, which you use to actually specify which data will be be displayed on the map and how to manipulate or process it on the fly before displaying it.

In this category, the following arguments are used to specify the data and how to process the data before displaying it on a data map. Let’s look each of these arguments in detail:

However, there is an issue with this command. The sales data we have is at the county level, but we want to display data at state level. How can we do it? Now we need theCombineDataBy argument.

So, in our example, since we want to display annual sales per product line, we need to divide the annual sales number by the product line count. So, we need to pass the Total Product Lines Sold field for this argument.

The hypothetical display data map command is now complete:

We have now finished the display data map task as we specified it at the beginning. Now it’s time to address the range specification.

The range specification argument group consists of the arguments that specify the data ranges and related color scheme to be used with the data map. What is a data range in the data map context? Data range is where you define the limits (lowest and highest) for your data to be displayed on the data map. Some ranges will be narrow, while others will be wide—this depends purely on the input data. Usually MapPoint 2004 does a good job of deciding which range types and orders to use depending on the input data. For most applications, leaving the default values would suffice. Still, let’s look at each argument in detail.

The range specification argument group consists of the following arguments:

So far, we have discussed the arguments you need to understand to work with data maps. If you are not anticipating using custom data range specifications, you can safely skip the following section on specifying custom ranges without losing any continuity or context.

The following sets of arguments are used only to specify a custom data range. Why do you need a custom data range? Say, for example, that you have sales data ranging from $10 to $10,000. If you want to consider a specific range of sales amount in your data map, say from $500 to $5,000, ignoring all other data, you need to use a custom data range specification that sets the range limits as $500 and $5,000. Remember, though, that there is a direct relationship between the DataRangeCount argument and the custom data range values, which is shown in Table 3-5.

Similar to the previous range count, range type, and custom range value relationships, there is one more relationship between map style and custom range values. For column chart and series column chart maps, the number of custom values is always set to five, and you need to set only the first and fifth custom range values.

With this introduction, let’s take a look at the custom range specification arguments in detail:

We have now finished a grand tour of the DisplayDataMap method argument list. If your head is spinning by now, don’t worry—I will discuss all of these concepts with some examples later in this chapter. For now, there is one last important issue that you need to understand in order to use this method in .NET: dealing with optional values .

The DisplayDataMap method (along with many other methods in the MapPoint 2004’s API) has optional arguments that can be safely omitted by passing nothing in COM/VB era. It’s not that simple when you call this method from .NET. Whether it’s C#, VB.NET, or any other .NET language, there is no notion of optional values that can be skipped in a method call. However, the .NET framework provides a type, System.Reflection.Missing.Value, which represents a COM optional value. So, when you are working with a method that has optional values, and you do not have any specific value to pass, you need to send the missing value instance:

    //Define missing argument for optional argument
       object missing = System.Reflection.Missing.Value;
    ....

    //Now display datamap
    MapPoint.DataMap datamap =
        dataset.DisplayDataMap(
        GeoDataMapType.geoDataMapTypeCategoricalColumn,
        datafields, GeoShowDataBy.geoShowByRegion1,
        GeoCombineDataBy.geoCombineByNone,
        GeoDataRangeType.geoRangeTypeDefault,
        GeoDataRangeOrder.geoRangeOrderDefault,
    6, 3, missing, missing, missing, missing, missing);

Now that you have a good understanding of data map styles and the DisplayDataMap method, it’s time write some code to display data maps. As a first step, let’s look at how to use the native demographic data that ships with MapPoint 2004 to display data maps. Next, we’ll look at some techniques to display external data (for your business) and to integrate the demographic data and your data.

Let’s write code to display a data map for these specifications. Assuming that you already have an instance of the MapPoint 2004 ActiveX Control in your Windows form, we will first get the demographic dataset:

    //Get a reference to the active map
    MapPoint.Map map = axMappointControl1.ActiveMap;

    //Get the MapPoint demographics dataset
    MapPoint.DataSet dataset
        = map.DataSets.GetDemographics(MapPoint.GeoCountry.geoCountryUnitedStates);

Now that we have the MapPoint 2004 demographic dataset, define the data field argument:

    //Define the data field name as a key
    object datafieldKey = "Population (2002)";
    //Now get the data field from the demographic dataset
    object[] datafields = new object[1];
    datafields[0] = dataset.Fields.get_Item(ref datafieldKey);

You might have noticed that I’m defining the datafields instance as an array of objects. You could also define it as a single object instance as long as you don’t need to pass more than one field name.

Next, define a few other arguments, such as color scheme and data range count:

    //Define the color scheme
    //Between 0 and 16; 3 represents orange/red shade
    int colorScheme = 3;

    //Define data range count
    //Between 1 and 8; 3 works for most
    int rangeCount = 3;

    //Define missing object optional values
    object missing = System.Reflection.Missing.Value;

Now we have everything we need to display a data map, and the following code snippet shows the actual DisplayDataMap method call:

    //Now call the display data map for sized circle map
    MapPoint.DataMap datamap =
            dataset.DisplayDataMap(MapPoint.GeoDataMapType.geoDataMapTypeSizedCircle,
                    datafields, MapPoint.GeoShowDataBy.geoShowByRegion1,
                    MapPoint.GeoCombineDataBy.geoCombineByNone,
                    MapPoint.GeoDataRangeType.geoRangeTypeDefault,
                    MapPoint.GeoDataRangeOrder.geoRangeOrderDefault,
                    colorScheme, rangeCount, missing, missing,
                    missing, missing, missing);

We are using the default values for range type and range order arguments.

Finally, make sure that you have the legend pane open so that you know how to interpret the data map; the following code shows how to set the legend pane state:

    //Now make sure to display legend pane
    axMappointControl1.PaneState = MapPoint.GeoPaneState.geoPaneLegend;

When you execute this code, a data map for population statistics per state, shown in Figure 3-11, is created.

Figure 3-11. Sized circle map for population per state

Remember that we have chosen to use the default data range type for this data map. A little investigation of the resulting datamap object properties (datamap.DataRanges.DataRangeType) reveals that MapPoint has chosen geoRangeTypeContinuousLog range type, so the resulting data map has three ranges with a low value of 400,000 and a high value of 35,000,000. While this data map does a good job of revealing which state has the largest population (California, with close to 35 million people!) it does not do a very good job indicating the state with smallest population (Wyoming, a quiet 500,000).

It might be useful to expand the data range a little by increasing the data range count to, say, eight (the maximum allowed value). However, changing the data range count to eight also requires a change in the range type (since the default data range does not support range count other than three); to meet this requirement, change the data range type to geoRangeTypeDiscreteEqualRanges. The following code reflects the two changes discussed:

    //Define data range count
    //Between 1 and 8; changing from 3 to 8
    int rangeCount = 8;

The new method call looks as follows:

    //Now call the display data map for sized circle map
    MapPoint.DataMap datamap =
            dataset.DisplayDataMap(MapPoint.GeoDataMapType.geoDataMapTypeSizedCircle,
                    datafields, MapPoint.GeoShowDataBy.geoShowByRegion1,
                    MapPoint.GeoCombineDataBy.geoCombineByNone,
                    MapPoint.GeoDataRangeType.geoRangeTypeDiscreteEqualRanges,
                    MapPoint.GeoDataRangeOrder.geoRangeOrderDefault,
                    colorScheme, rangeCount, missing, missing,
                    missing, missing, missing);

When you execute the code with these new settings, the data map displayed looks like Figure 3-12.

Figure 3-12. Sized circle population using larger data range

Even though the data map has an expanded data range, it’s still unclear from the map which state has the smallest population, so you need to use the custom data ranges by specifying custom ranges .

In this case, we clearly need a range that starts much lower than the starting range shown in Figure 3-4 (0 to 4,379,999 would be appropriate here). So, define a custom data range as shown below:

    //Define custom range values
    //Since the range count is 8,
    //we are defining 9 range objects
    object[] arrayOfCustomValues = new object[9];
    //Stretch the lower end by defining ranges
    //pretty close to each other
    arrayOfCustomValues[0] = 250000;
    arrayOfCustomValues[1] = 500000;
    arrayOfCustomValues[2] = 750000;
    arrayOfCustomValues[3] = 1000000;
    //Set the maximum value
    arrayOfCustomValues[8] = 35000000;

In this code, I have just defined the starting range as 250,000 and set the next three ranges in 250,000 increments. What I’m really trying to do here is to stretch the lower end of the data range to have smaller ranges to accommodate better size variation in the circles. I also set the maximum limit for the data to be 35,000,000.

The DisplayDataMethod call with this custom data range specification is shown here:

    //Now call the display data map for sized circle map
    MapPoint.DataMap datamap =
            dataset.DisplayDataMap(MapPoint.GeoDataMapType.geoDataMapTypeSizedCircle,
                    datafields, MapPoint.GeoShowDataBy.geoShowByRegion1,
                    MapPoint.GeoCombineDataBy.geoCombineByNone,
                    MapPoint.GeoDataRangeType.geoRangeTypeDiscreteEqualRanges,
                    MapPoint.GeoDataRangeOrder.geoRangeOrderDefault,
                    colorScheme, rangeCount, arrayOfCustomValues, missing,
                    missing, missing, missing);

The resulting data map is shown in Figure 3-13.

Now, as you can see, the circle in the state of Wyoming looks smallest of all the circles, so it has the smallest population in all states (only 499,904). Using custom data range specification, we could display both the most and least populous states. While we are at it, we can also customize the legend pane to reflect what we are trying to achieve.

Figure 3-13. Sized circle population chart with custom data range

You can customize the legend pane names by defining an array of custom names. The number of the custom name array must be equal to the data range count. In our example the range count is set to eight, so we need to define an array of objects of size eight and assign names for each range:

    //Define custom name array to reflect
    //their populations
    object[] arrayOfcustomNames = new object[8];
    arrayOfcustomNames[0] = "Hello! Anyone home?";
    arrayOfcustomNames[1] = "Small and happy!";
    arrayOfcustomNames[2] = "Nice and pleasant.";
    arrayOfcustomNames[3] = "Have room for some more!";
    arrayOfcustomNames[4] = "Just about the right size.";
    arrayOfcustomNames[5] = "Still not bad to live here!";
    arrayOfcustomNames[6] = "Kind of stuffy here.";
    arrayOfcustomNames[7] = "Man, too crowded!";

Calling the DisplayDataMap method with custom names results in the map shown in Figure 3-14.

The legend pane now contains custom names. They may look (and sound) funny. If you are thinking, “How can you judge whether a state is too crowded based only on population? We’re supposed to look at the population density to determine whether it is too crowded or not,” these are the exactly right questions to ask. I should display population density (population divided by area of the state) to justify my custom labels. We need to write code to use the DivideBy field.

Figure 3-14. Sized circle population map with custom legend pane

To create a population density map, you need to divide the population by the total area of the corresponding state. The area of the state is available in the demographic data of the “Area in Square Miles” field. To divide the state population with area, we have only to obtain a reference to the “Area in Square Miles” field and pass it as a DivideByField argument:

    //Define data field indexes
    object popIndex = "Population (2002)";
       object areaIndex = "Area in Square Miles";

    //Get demographic dataset
    MapPoint.DataSet dataset =
             map.DataSets.GetDemographics(MapPoint.GeoCountry.geoCountryUnitedStates);

    //Get population field
    MapPoint.Field datafield = dataset.Fields.get_Item(ref popIndex);
       //Get area field
    MapPoint.Field divideField = dataset.Fields.get_Item(ref areaIndex);

    ...

    //Define custom range values
    //Since the range count is 8,
    //we are defining 9 range objects
    object[] arrayOfCustomValues = new object[9];
    //Set the custom range values
    arrayOfCustomValues[0] = 1;
    arrayOfCustomValues[1] = 5;
    arrayOfCustomValues[2] = 10;
    arrayOfCustomValues[3] = 50;
    //Set the maximum value
    arrayOfCustomValues[8] = 10000;

    ...

    //Now display Map
    MapPoint.DataMap datamap =
        dataset.DisplayDataMap(MapPoint.GeoDataMapType.geoDataMapTypeSizedCircle,
        datafield, MapPoint.GeoShowDataBy.geoShowByRegion1,
        MapPoint.GeoCombineDataBy.geoCombineByNone,
        MapPoint.GeoDataRangeType.geoRangeTypeDiscreteEqualRanges,
        MapPoint.GeoDataRangeOrder.geoRangeOrderHighToLow,
        colorScheme,rangeCount, arrayOfCustomValues, arrayOfcustomNames,
        divideField, missing, missing);

    //Set proper legend title
       datamap.LegendTitle = "State Population Density";

    //Zoom to show compelte data mapdataset.ZoomTo( );

As you can see from this code, the divideField is the “Area in Square Miles” field from the demographic dataset. Also, notice that I redefined the custom data range value to accommodate the new data values we’ll have after the division process. The new concepts that I have included in this code are setting the LegendTitle property of the data map and zooming to the full data map view by calling the ZoomTo method on the dataset object. The resulting data map is shown in Figure 3-15.

From the data map in Figure 3-15, you can see that Alaska has the lowest population density at about 1.1 people per square mile. When you zoom in to the east coast, you can tell that Washington D.C has the highest population density at about 1,000 people per square mile. There is one more thing you can do with custom data ranges: filter unwanted data from the data map.

By specifying custom data range values, you can show only states with population densities below 100 people per square mile.

    //Set the range so that you only show
    //states with population density
    //below 100 people/Sq. Mile
    arrayOfCustomValues[0] = 1;
    arrayOfCustomValues[1] = 5;
    arrayOfCustomValues[2] = 10;
    arrayOfCustomValues[3] = 50;
    //Set the maximum value
    arrayOfCustomValues[8] = 100;

Figure 3-15. Sized circle population density map

You can also specify any other data range count to achieve the same effect.

Finally, to use the Data Mapping Wizard user interface from the MapPoint 2004 product in your application, call the DataSets.ShowDataMappingWizard method:

    MapPoint.DataMap datamap =
            map.DataSets.ShowDataMappingWizard(this.Handle.ToInt32( ),
             null, MapPoint.GeoDataMappingPage.geoDataSetPage);

This method takes the parent window handle, a DataSet instance, if you want to import the data into an existing data set and onto the starting page of the wizard. You can pass null if you want to import the data into a new DataSet instance.

Next, let’s switch gears and look at how to use your business data to draw data maps.

Like the DisplayDataMap method, the ImportData method is also exposed on the DataSets collection, mainly due to the fact that the imported data will be stored as a data set in MapPoint and made available from the DataSets collection for later use. The signature for the ImportData method is as follows:

    DataSets.ImportData(DataSourceMoniker, ArrayOfFields, Country, Delimiter, ImportFlags)

Let’s discuss each argument in detail.

To import external data into a MapPoint 2004 DataSet, indicate the data source specifics, such as the path to the data source for a text file or an Outlook contacts file moniker, and pass this as the DataSourceMoniker argument. Even though this argument is an Object type, you can pass a string value. However, since there is no direct interface available in MapPoint 2004 to work with relational data bases such as SQL Server, you have to write code to connect to the SQL server and read the data to be imported into a DataSet (which we will see later in this chapter).

The next argument is the ArrayOfFields. This argument is used to import specific fields from the data source. This field is a two-dimensional array of objects. One dimension holds the data field names form the data source, and the other holds the field type specification. The field style specification is defined by using the GeoFieldType enumeration, which provides values such as geoFieldSkipped, geoFieldRegion1, geoFieldData, and so on. Each of these values is used to specify how the data field from the source should be treated in the MapPoint DataSet. The following code snippet shows how to define this argument and cite the field specifications. Say you have a text file that has the following tab-delimited fields:

    ID  State     Country   Our Sales($) Competitor A Sales($) Competitor B Sales($)
    1   Alabama   US        531          2859                  2810
    2   Arizona   US        4872         328                   193

You can specify the field specification:

    //Define field specification
    object[,] fieldSpecifications = null;

    fieldSpecifications = new object[6,2];

    //Specify what fields are geographic and what fields are not
    fieldSpecifications[0,0] = "ID";
    fieldSpecifications[0,1] = MapPoint.GeoFieldType.geoFieldSkipped;

    fieldSpecifications[1,0] = "State";
    fieldSpecifications[1,1] = MapPoint.GeoFieldType.geoFieldRegion1;

    fieldSpecifications[2,0] = "Country";
    fieldSpecifications[2,1] = MapPoint.GeoFieldType.geoFieldCountry;

    fieldSpecifications[3,0] = "Our Sales($)";
    fieldSpecifications[3,1] = MapPoint.GeoFieldType.geoFieldData;

    fieldSpecifications[4,0] = "Competitor A Sales($)";
    fieldSpecifications[4,1] = MapPoint.GeoFieldType.geoFieldData;

    fieldSpecifications[5,0] = "Competitor B Sales($)";
    fieldSpecifications[5,1] = MapPoint.GeoFieldType.geoFieldData;

The next argument is the country. You have to specify the country enumeration to indicate the data for the country with which you are working. This argument’s type is GeoCountry, an enumeration.

The other two arguments are the flags that aid the import process to understand how the data is delimited and data source-specific interfacing. I will discuss these flags later in this section.

Building on this introduction, let’s see how to import data from different data sources.

The DataSets.ImportData method can import data from text files with tab, semicolon, and comma delimitation. The following sample code shows how to import a tab-delimited text file with default field settings:

    //Using the MapPoint Sample Sales data from txt file
    //This data file can be found on the companion CD in
    //the Chapter 03 directory.
    string filePath = @"D:MapPoint3Sample DataSales.txt";
    //Define field specification
    //Since we want to import all fields, we can just
    //go with default import
    object missing = System.Reflection.Missing.Value;

    //Import data and create a dataset
    MapPoint.DataSet dataset =
        map.DataSets.ImportData(filePath, missing,
        MapPoint.GeoCountry.geoCountryUnitedStates,
        MapPoint.GeoDelimiter.geoDelimiterTab,
        MapPoint.GeoImportFlags.geoImportFirstRowIsHeadings);

When you run this code, each row from the text file is imported into a newly created DataSet, and a pushpin is placed on the map to indicate the location of the record. The new DataSet created with this method is also called a PushpinDataset. You can also call the DataSet.DisplayPushpinMap method to display the contents of a dataset. This method places a pushpin for each record in the corresponding location.

Also, as you might have noticed already, the Delimiter argument in this case is set to geoDelimiterTab, since the source data file has records with tab delimited columns; you can also use the geoDelimiterDefault value. However, in that case MapPoint determines the delimitation based on the filename. By design, MapPoint assumes that the delimitation is a tab for .txt, .asc, and .tab files, while delimitation is a comma for .csv files. Finally, The ImportFlags argument is of GeoImportFlags type, an enumeration whose value is set to GeoImportFlags.geoImportFirstRowIsHeadings to indicate that the first row is a header.

After importing the data, you can access the fields in this newly created pushpin dataset as you would access fields in the MapPoint demographic dataset. The following code shows how to access the fields from the imported dataset to display a data map. Say, for example, you have just imported a text file in the following format:

    ID  State     Country   Our Sales($) Competitor A Sales($) Competitor B Sales($)
    1   Alabama   US        531          2859                  2810
    2   Arizona   US        4872         328                   193

Now you can access the data and display a sized pie chart data map to compare your company sales with the other two competing companies. Pie chart maps are great for comparing data side-by-side:

    //Define data map columns
    //These indexes come in the same order as
    //the fields in the text file
    object oursalesIndex = 4; //Fourth field from the text file
    object compAsalesIndex = 5; //Fifth field from the text file
    object compBsalesIndex = 6; //Sixth field from the text file

    //Now get fields
    object[] datafields = new object[3];
    datafields[0] = dataset.Fields.get_Item(ref oursalesIndex);
    datafields[1] = dataset.Fields.get_Item(ref compAsalesIndex);
    datafields[2] = dataset.Fields.get_Item(ref compBsalesIndex);

    //Now display datamap
    MapPoint.DataMap datamap =
        dataset.DisplayDataMap(MapPoint.GeoDataMapType.geoDataMapTypeSizedPie,
                            datafields, MapPoint.GeoShowDataBy.geoShowByRegion1,
                              MapPoint.GeoCombineDataBy.geoCombineByNone,
                              MapPoint.GeoDataRangeType.geoRangeTypeDefault,
                              MapPoint.GeoDataRangeOrder.geoRangeOrderDefault,
                              6, 3, missing, missing, missing, missing, missing);
    //Set the legend title
    datamap.LegendTitle = "Sales by State";

    //Set the legend pane
    axMappointControl1.PaneState = MapPoint.GeoPaneState.geoPaneLegend;

The previous code displays a data map that compares your sales with your competitor company’s sales, as shown in Figure 3-16.

Figure 3-16. Sized pie chart for sales comparison (Color Plate 6)

The map in Figure 3-16 contains a significant amount of information, and there are some immediate conclusions you can draw from it. I have listed a few of them:

The list of conclusions that can be drawn can go on and on once you get into the details of each market segment, your share of the market segment, your competitor’s share, and so on. To get there, though, you can easily import your business data and process that data using location to help you make intelligent and informed business decisions.

You may be wondering, “How does MapPoint understand how each record is linked to a location?” You are right that we haven’t specified anything of that nature to tell MapPoint which column is a location column from the text file, neither in the import code nor in the data map display code. So how does it understand? It’s actually pretty simple. MapPoint understands keywords like “state,” “country,” “Zip Code,” etc. and maps them to the appropriate geographic region. In this example, MapPoint automatically associated each record with the state location.

So, what happens if you have location data in an obscurely named column, say, “LocX?” Can MapPoint interpret it as a location and map the record to that location? No. That’s when you need to help MapPoint understand your data using the ArrayOfFields specification argument.

When no location column is clearly named or when you have 200 columns of which you want only 10 columns for your data map, you need to specify the field specifications to help MapPoint understand your data. Say, for example, you have a text file as a data source with the following data:

    ID  LocX     Land   Our Sales($) Competitor A Sales($) Competitor B Sales($)
    1   Alabama   US        531          2859                  2810
    2   Arizona   US        4872         328                   193

Imagine that the requirement is only to import the state field (named LocX) and your sales field (named “Our Sales ($)”), ignoring the rest of the fields. You have to define field specifications:

    //Define field specification
    object[,] fieldSpecifications = null;

    //Declare field specifications to indicate about
    //each and every field - so we need a total of
    //6 fields since we have 6 fields in the txt file
    fieldSpecifications = new object[6,2];

    //Specify the field name
    fieldSpecifications[0,0] = "ID";
    //Indicate MapPoint not to import it
    fieldSpecifications[0,1] = MapPoint.GeoFieldType.geoFieldSkipped;

    //Specify the field name
    fieldSpecifications[1,0] = "LocX";
    //Indicate MapPoint that this is a State field
    fieldSpecifications[1,1] = MapPoint.GeoFieldType.geoFieldRegion1;

    fieldSpecifications[2,0] = "Land";
    fieldSpecifications[2,1] = MapPoint.GeoFieldType.geoFieldCountry;

    //Specify the field name
    fieldSpecifications[3,0] = "Our Sales($)";
    //Indicate MapPoint that this is one of the required
    //data fields so that MapPoint imports it
    fieldSpecifications[3,1] = MapPoint.GeoFieldType.geoFieldData;

    //Skip all other fields
    . . .

    //Now import the data and create a dataset
    MapPoint.DataSet dataset =
        map.DataSets.ImportData(filePath, fieldSpecifications,
        MapPoint.GeoCountry.geoCountryUnitedStates,
        MapPoint.GeoDelimiter.geoDelimiterTab,
        MapPoint.GeoImportFlags.geoImportFirstRowIsHeadings);

The GeoFieldType enumeration value is used to inform MapPoint about any given field from the data source.

Once you import your data into a dataset, using either a default import or a customized import using the custom field specifications, you can integrate your data with the demographic data and display data map using both datasets.

MapPoint 2004 allows you to draw more than one data map on any given ActiveMap instance meaning that you can display an Annual Average Spending data map using the demographic data set, and then display a data map of your sales on top of the existing data map. The resulting data map contains data from both datasets and gives you an idea of how to make use of demographic data in conjunction with your business data to make intelligent business decisions.

Now that you know how to import data from a text source and how to customize the import using field specifications, let’s look at importing data from other data sources.

Importing data from a Microsoft Excel file is no different from importing data from a text file. To use an Excel data source with the MapPoint 2004 API, you need to know how to define an Excel data source moniker. Say you have an Excel file with sales data in the C:MapPointData directory. Also, assume that the actual sales data is in Sheet2 of the Excel book. The data source moniker would be:

    string filePath = @"C:MapPointDataSales.xls!sheet2";

Once you have the proper data source moniker ready, importing the data is easy. It is similar to what you have seen in case of a text file:

    //Define the missing field
    object missing = System.Reflection.Missing.Value;
    //Import data and create a dataset
    MapPoint.DataSet dataset =
        map.DataSets.ImportData(filePath, missing,
        MapPoint.GeoCountry.geoCountryUnitedStates,
        MapPoint.GeoDelimiter.geoDelimiterDefault,
        MapPoint.GeoImportFlags.geoImportExcelSheet);

However, if you are importing data from an Excel source, and you want to limit your data to a particular row and column range, the moniker and the data import flag will be different. Table 3-7 shows different data import options, corresponding monikers, and the appropriate data import flags.

The A1 and R1C1 ranges are used to select a particular set of rows and columns from the source Excel sheet.

Support for importing data from a Microsoft Access database is built into MapPoint 2004 APIs. An import from an Access database differs from any other data source imports that we’ve seen so far only in terms of defining the data moniker and specifying an appropriate import flag.

For example, if you have a sample sales Access database in the C:MapPointDataSales.mdb directory, and if it has a table called SalesTable that contains sales information based on location, you can define a moniker as follows:

    string filePath = @"C:MapPointDataSales.mdb!SalesTable";

Once you have the right moniker, it is pretty simple to import the data:

    //Define missing argument for optional argument
    object missing = System.Reflection.Missing.Value;
    //Import data and create a dataset
    MapPoint.DataSet dataset =
            map.DataSets.ImportData(filePath, missing,
            MapPoint.GeoCountry.geoCountryUnitedStates,
            MapPoint.GeoDelimiter.geoDelimiterDefault,
            MapPoint.GeoImportFlags.geoImportAccessTable);

Microsoft Access also supports data source monikers in the query form. If you have a query, namely SalesQuery in your Access database, you can import data from it using the following moniker and import flag arguments:

       string filePath = @"C:MapPointDataSales.mdb!salesQuery";

    //Define missing argument for optional argument
    object missing = System.Reflection.Missing.Value;
    //Import data and create a dataset
    MapPoint.DataSet dataset =
            map.DataSets.ImportData(filePath, missing,
            MapPoint.GeoCountry.geoCountryUnitedStates,
            MapPoint.GeoDelimiter.geoDelimiterDefault,
            MapPoint.GeoImportFlags.geoImportAccessQuery);

Next, let’s look at how to import data from a SQL database.

Unlike the data imports that we have seen so far, MapPoint 2004 does not have any built-in support for importing data from relational databases such as SQL 2000. Using the .NET Framework’s ADO.NET base classes , however, you can easily import data. So, in this section, I will show how to import data from SQL into MapPoint. In the following example, I import customer order information from the Orders table in the standard NorthWind database.

Since there is no ImportData method that both supports a SQL data source and creates a resulting DataSet, you need to create a data set yourself in which to import data. The first step is to create a new DataSet instance in the DataSets collection:

    //See whether there is an existing datasetwith the same name
    object datasetName = "NorthWind Orders";
    if(map.DataSets.Count > 0 && map.DataSets.get_Item(ref datasetName) != null)
        //If so, delete it
        map.DataSets.get_Item(ref datasetName).Delete( );
    //Now create a new dataset
    MapPoint.DataSet dataset = map.DataSets.AddPushpinSet("NorthWind Orders");

I check for an existing DataSet with the name NorthWind Orders and delete it if it already exists. We need to perform this check since you cannot create a dataset with the same name twice in one map session; MapPoint throws an exception when you create a duplicate.

Once you have the DataSet ready to import the data, connect to the SQL Server using the ADO.NET SqlConnection class:

    //Define a connection string
    string sqlConnectionString =
       "server=localhost;database=northwind;User Id=sqluser;Password=password";

    //Define a connection object
    System.Data.SqlClient.SqlConnection connection
        = new System.Data.SqlClient.SqlConnection(sqlConnectionString);

Now that your application is ready to connect to SQL Server, the next step is to create a SQL query using the ADO.NET SqlCommand class to get the purchase order records from the orders database:

    //Define a SQL query
    string sqlQueryString = "SELECT CustomerID as ContactName, ShipName as CompanyName,
ShipAddress as Address, ShipCity as City, ShipRegion As Region, ShipPostalCode as
PostalCode, ShipCountry as Country FROM Orders WHERE ShipCountry = 'USA'";

    //Define a command object
    System.Data.SqlClient.SqlCommand command =
            new System.Data.SqlClient.SqlCommand(sqlQueryString, connection);

Since we have the SQL command instance ready, we need to execute the command, read through the records, and import each one of them into the DataSet instance that we have created earlier.

    try
       {
          //Open the connection
          connection.Open( );
          //Get a sql reader from the query
          System.Data.SqlClient.SqlDataReader sqlReader =
                    command.ExecuteReader(System.Data.CommandBehavior.CloseConnection);
          if(sqlReader != null)
           {
              while(sqlReader.Read( ))
               {
                  //Get the name of the customer
                  string customername  = sqlReader["ContactName"] as String;
                  //Get the company name
                  string companyname  = sqlReader["CompanyName"] as String;
                  //Get the address string
                  string address = sqlReader["Address"] + ", " + sqlReader["City"] + ",
                                 " + sqlReader["Region"] + ", " +
                                  sqlReader["PostalCode"] + " " + sqlReader["Country"];

                 //Find location
                 MapPoint.Location location = null;
                 try
                   {
                      //Find the address
                      MapPoint.FindResults findrs = map.FindResults(address);
                      //If no results found, skip to next record
                      if(findrs == null || findrs.Count <= 0)
                          throw new Exception(address);
                      //Get the location
                      location = findrs.get_Item(ref index) as MapPoint.Location;
                      //Create a pushpin
                      if(location != null)
                       {
                         MapPoint.Pushpin pushpin =
                              map.AddPushpin(location, companyname);
                         //Assign the contact name
                         pushpin.Note = "Contact : " + customername;
                            //Move to the pushpin dataset
                         pushpin.MoveTo(dataset);
                       }
                   }
              catch
                   {
                      //Do some logging
                   }
            }

            //Close the reader; this will automatically close the connection
            //due to the command behavior setting during the ExecuteReader method
            sqlReader.Close( );
          }
        }
    catch
        {
          //Do clean up
        }

This code loops through the records from the SqlDataReader instance, finding the corresponding location for each ship address in the orders table, adding a pushpin to the map for that location, and, most importantly, at the end, moving that pushpin to the dataset created previously using the Pushpin.MoveTo method.

Upon executing this code, we now have a pushpin DataSet that can be treated like any imported DataSet that we have seen so far in this chapter.

Finally, to use the MapPoint 2004 Import Data Wizard, call the DataSets.ShowImportWizard method.

So far, we have used MapPoint DataSets to display data maps. There are more powerful business intelligence applications you can build with MapPoint 2004.

A MapPoint DataSet is very versatile—you can build business applications to assist in making intelligent business decisions (similar to the one you have seen at the beginning of this section with pie charts), but now let’s take a simple scenario that does not include a data map but still relates to business intelligence and decision making. The DataSet that I will use for this example is the NorthWind Orders dataset that we just created.

Let’s tackle a simple form of a supply-chain optimization problem: your company has warehouses on the West Coast where all of the West Coast shipments come from. Considering that the U.S. West Coast is very long, your CEO wants to know whether there is a way to cut transportation costs and boost your company’s bottom-line. One simple way to answer his question is by investigating all shipped orders and finding out how many orders are transported from any given warehouse for more than, say, 100 miles. Next, investigate whether there is a possibility of opening another warehouse in a place closer to the customers in that area. Then you could cut down the transportation for the shipments. Can MapPoint 2004 do this? Using the DataSet querying capabilities, absolutely! Let’s see how.

Using the AddShape method from the Shapes collection, you can add a circle or oval at any location on the current map. The AddShape method accepts the type of shape, which is of MapPoint.GeoAutoShapeType enumeration, and the location around which to draw this shape at the same height and width.The GeoAutoShapeType enumeration supports drawing ovals, circles, and rectangles. The following example shows how to draw a circle around the location Seattle, WA:

    //Find a location
    object index = 1;
    MapPoint.Location location =
            (MapPoint.Location) map.FindResults("Seattle").get_Item(ref index);

    //Add a circle with radius = 50 miles
    MapPoint.Shape shape =
            map.Shapes.AddShape(MapPoint.GeoAutoShapeType.geoShapeOval,
                            location, 50, 50);
    //Zoom to shape
    shape.Location.GoTo( );

To draw an oval, pass a different height and width. What if you want to draw a circle that shows the radius? You’ll have to use GeoAutoShapeType.geoShapeRadius as the shape type. You can also draw a rectangle using the same method but passing the GeoAutoShapeType.geoShapeRectangle value for the shape type argument.

Drawing a line using MapPoint 2004 is very simple. Since a line is basically a shape that connects only two locations, pass two locations to this method. So, if you want to draw a line between Seattle, WA, and Los Angeles, CA, use the following code:

    object index = 1;
    //Find Seattle, WA
    MapPoint.Location location1 =
         (MapPoint.Location) map.FindResults("Redmond, WA").get_Item(ref index);
    //Find Los Angeles, CA
    MapPoint.Location location2 =
         (MapPoint.Location) map.FindResults("Los Angeles, CA").get_Item(ref index);

    //Now, add a line
    MapPoint.Shape shape = map.Shapes.AddLine(location1, location2);

While a line connects two locations, a polyline connects more than two locations. The AddPolyline method takes an array of locations as an argument and draws a polyline connecting the input locations.

The following example shows how to draw a polyline connecting Redmond, WA, Portland, OR, and Los Angeles, CA:

    object index = 1;

    MapPoint.Location location1 =
      (MapPoint.Location) map.FindResults("Redmond, WA").get_Item(ref index);
    MapPoint.Location location2 =
      (MapPoint.Location) map.FindResults("Portland, OR").get_Item(ref index);
    MapPoint.Location location3 =
      (MapPoint.Location) map.FindResults("Los Angeles, CA").get_Item(ref index);

    //Add a polyline
    MapPoint.Shape shape =
    map.Shapes.AddPolyline(new MapPoint.Location[] {location1, location2, location3});

You can extend the polyline to draw a polygon by closing the polyline to form a polygon. For example, if you have four locations that you are drawing a polyline with, you can form a polygon using these four locations by connecting the last location with the first location. The following example shows how to create a polygon using the AddPolyline method:

    object index = 1;
    MapPoint.Location location1 =
      (MapPoint.Location) map.FindResults("Redmond, WA").get_Item(ref index);
    MapPoint.Location location2 =
      (MapPoint.Location) map.FindResults("Portland, OR").get_Item(ref index);
    MapPoint.Location location3 =
      (MapPoint.Location) map.FindResults("Los Angeles, CA").get_Item(ref index);
    MapPoint.Location location4 =
      (MapPoint.Location) map.FindResults("Boise, ID").get_Item(ref index);

    //Add a ployline
    MapPoint.Shape shape =
        map.Shapes.AddPolyline(new MapPoint.Location[] {
                           location1, location2, location3, location4, location1});

Since “location4” is now connected back to “location1,” this method draws a polygon that includes the aforementioned four locations as vertices.

For any non-GeoAutoShapeType shape, you can access vertices/locations at the vertices that make up that shape. You can obtain values for vertices for any shape that is drawn using AddLine or AddPolyLine methods:

    //Add a ploygon
    MapPoint.Shape shape = map.Shapes.AddPolyline(new MapPoint.Location[]
                    {location1, location2, location3, location4, location1});

    //Now get the vertices for this polygon
    object[] vertices = shape.Vertices as object[];
    foreach(object vertex in vertices)
    {
        MapPoint.Location loc
            = vertex as MapPoint.Location;
    }

The vertices are exposed as an array of objects, and you have to typecast them as Location objects to access the location properties of the vertex.

Sometimes you have to find distance from a given point or location to a shape. In such cases, since there is no direct API available for this purpose, use the vertices of the shape to find the nearest vertex to the input location using the Location.DistanceTo method:

    //Start with a location object
    MapPoint.Location loc;
    //Obtain a valid location instance such as Redmond, WA
    //and assign it to loc object.
    . . .

    //Now get the vertices a polygon from where
    //we want to measure distances
    object[] vertices = shape.Vertices as object[];
    foreach(object vertex in vertices)
    {
        MapPoint.Location shapeLoc
            = vertex as MapPoint.Location;
        //Now get distance
        Console.WriteLine(shapeLoc.DistanceTo(loc));

    }

While this is does not give exactly the nearest location, it provides a workaround for this situation.

Finally, the Shapes collection provides a method to draw a text box on the map. This is useful to draw labels that are specific to your business needs. The following example shows how to draw a text box at the center of a circle that indicates your market area:

    //Find a location
    object index = 1;
    MapPoint.Location location =
        (MapPoint.Location) map.FindResults("SEA").get_Item(ref index);

    //Add a circle
    MapPoint.Shape shape =
            map.Shapes.AddShape(MapPoint.GeoAutoShapeType.geoShapeOval,
            location, 150, 150);

    //Draw a text box
    MapPoint.Shape tBox = map.Shapes.AddTextbox(location, 50, 20);

    //Now assign text to the text box
    object name = "MarketingAreaTextBox";
    //Assign it to the shape
    tBox.Name = name.ToString( );
    //Now assign text by accessing the shape from the collection
    map.Shapes.get_Item(ref name).Text = "Marketing Zone A";

The shape can be accessed via either the name of the shape or the index of the shape from the Shapes collection.

So far, you have seen how to draw shapes. Next, let’s look at how to customize the shape’s appearance using the MapPoint 2004 APIs.

When you draw a shape in MapPoint 2004, the shape is drawn with a default line width and color. However, you can change these attributes by altering the settings available using the Shape.Line property, which is a LineFormat object. The LineFormat object exposes Width and ForeColor properties to alter the width and color of the line. The properties are Integer type. The integer represents the RGB color value of the OLE color format. In order to convert the .NET Color structure to the OLE color structure , use the .NET Framework’s ColorTranslator class available in the System.Drawing namespace. The following example shows how to set the line color and line width of a circle shape:

    //Add a circle
    MapPoint.Shape shape =
      map.Shapes.AddShape(MapPoint.GeoAutoShapeType.geoShapeOval, location, 75, 75);

    //Customizing the line format
    shape.Line.Weight = 1;
    shape.Line.ForeColor = ColorTranslator.ToOle(Color.LightSteelBlue);

You can change the visibility of the line using the LineFormat.Visible property:

    //Do not want to show the line
    shape.Line.Visible = false;

You can change the fill color of a shape using the Shape.Fill property, which is a FillFormat object. The FillFormat object exposes properties such as ForeColor and Visible to change the appearance of the shape. The following sample shows how to change the fill color of a circle shape:

    //Add a circle
    MapPoint.Shape shape =
      map.Shapes.AddShape(MapPoint.GeoAutoShapeType.geoShapeOval, location, 75, 75);

    //Customizing a shape look-and-feel
    shape.Fill.ForeColor = ColorTranslator.ToOle(Color.LightBlue);
    //Set visibility to true
    shape.Fill.Visible = true;

When I talk about fill color, you may be wondering whether it is possible to fill the shape with alpha blending (or translucency ). Actually, OLE fill color does not support alpha blending; however, MapPoint 2004 allows you to create and fill shapes so that the map beneath the shape is still visible.

The Shape object has a method, ZOrder, which you can use to make a shape transparent even with fill color visible. The ZOrder method takes an argument of type GeoZOrderCmd enumeration, which provides values for sending the shape behind objects (such as roads on the map), bringing it in front of objects, or sending it behind another shape. To make a shape transparent by sending it behind the roads, use the following code:

    //Add a circle
    MapPoint.Shape shape =
       map.Shapes.AddShape(MapPoint.GeoAutoShapeType.geoShapeOval, location, 75, 75);

    //Customizing a shape look-and-feel
    shape.Fill.ForeColor = ColorTranslator.ToOle(Color.LightBlue);
    shape.Fill.Visible = true;
    shape.Line.Weight = 1;
    shape.Line.ForeColor = ColorTranslator.ToOle(Color.LightSteelBlue);

    //Send back to the map
   shape.ZOrder(MapPoint.GeoZOrderCmd.geoSendBehindRoads);

Sometimes you have to toggle the visibility of a shape completely. Even though the MapPoint 2004 API provides Visible properties for both line and fill color of shapes, setting them as false does not make the shape disappear completely. You can work around this by moving a shape to an obscure location (such as the North Pole) and bringing it back to its original location when needed. The following steps show how to achieve the visibility toggling effect:

This method works well within a single application session. However, if you want to persist the shape across the application sessions, you may have to persist the shape name and the original location in an external store, such as a config file or a text file.

Now that you know how to draw shapes and customize their look and feel, it’s time to explore using the shapes for location information.