When you think of mapping in general, the first thing that comes to mind is finding a location and their associated latitude/longitude - whether it is a place (as in a point of interest) or an address. A place is a general location that is referred by its commonly known name; on the other hand the address is a more detailed specification of a location. For example, one of the most known places in Seattle around the world is “Space Needle”, but the actual address of the Space Needle is 498 Broad St, Seattle, WA 98109.

Using MapPoint you can find both places and addresses among other things.

The code snippet below shows how to find a place:

//Create an instance of ApplicationClass
MapPoint.ApplicationClass app = new MapPoint.ApplicationClass();
//Get a reference to the Map instance via the ActiveMap property
MapPoint.Map map = app.ActiveMap;

The MapClass exposes a method, FindPlaceResults, which returns all places that matches the input query. This method takes place name as string as an input and returns FindResults, which is a collection of locations found. The following code shows the FindPlaceResults method call:

//Call FindPlaceResults on the MapClass instance
MapPoint.FindResults findResults = map.FindPlaceResults(“Space Needle”);

Similarly, you can find addresses using the FindAddressResults method, as shown below:

//Create an instance of the MapPoint application class
MapPoint.ApplicationClass app = new MapPoint.ApplicationClass();
//Get the Map object from the application object
MapPoint.Map map = app.ActiveMap;
//Call the FindAddressResults method
MapPoint.FindResults findResults = map.FindAddressResults(
"498 Broad St",
"Seattle",
string.Empty,
"WA",
"98109",
MapPoint.GeoCountry.geoCountryUnitedStates);

Finally, if you don’t know if an input is a place (POI) or an address, use FindResults method, as shown below:

//Works with finding addresses
MapPoint.FindResults findAddressResults
= map.FindResults("498 Broad St, Seattle, WA, 98109");
//Works with finding places
MapPoint.FindResults findPlaceResults
= map.FindResults("Space Needle");

Now you just have to iterate through find results to get the location information in each case.

To learn more about this topic and other related topics, please buy Programming MapPoint in .NET

Find method calls (both FindPlaceResults and FindAddressResults) in MapPoint returns the FindResults instance that contains all the locations that matched the input query. Each location that matched the input place is represented as an instance of MapPoint.Location class in the FindResults object. Even though the FindResults class is essentially a collection of Location objects, its behavior is quite different (blame the COM legacy) from any .NET collection in that you can’t really access the members of the collection with their index as you would in a generic .NET collection.

Having said that you can still access the collection members in the following ways:

Using the Get accessor method

Collections are implemented using two special accessor methods called get_Item and set_Item. These special methods are generated by the .NET compiler for every publicly exposed property. In case of FindResults instance, even though the Items read-only property is not exposed in the interoperable assembly, get_Item method is still implemented internally. The only differences from the conventional .NET get_Item method are that this method takes the index value as an object passed by reference (for COM marshalling purposes) and the index starts from 1 instead of 0.
The following code shows how to use the get_Item accessor method to iterate through the list of Location objects in the FindResults collection:

//Create an object to hold index value
object index = null;
//Start with index 1 instead of 0
for(int i=1; i<=findResults.Count; i++) { //Box the integer value as an object index = i; //Pass the index as a reference to the get_Item accessor method MapPoint.Location loc = findResults.get_Item(ref index) as MapPoint.Location; if(loc != null) //do something intersting }

Using an enumerator

You can also access the list of Locations from FindResults instance using the enumeration. The FindResults instance exposes a method, GetEnumerator, to get an enumerated list of locations. Using this enumerator instance, you can loop through the list of locations as shown below:

//Get an enumerator using the GetEnumerator method
IEnumerator locationEnumerator = findResults.GetEnumerator();
//Loop through the location instances to get the names
while(locationEnumerator.MoveNext())
{
MapPoint.Location loc = locationEnumerator.Current as MapPoint.Location;
//do something interesting
}

To learn more about this topic and other related topics, please buy Programming MapPoint in .NET

Location class from MapPoint object model exposes the FindNearby method to find POI around a location. The only parameter that the FindNearby method takes is distance as type System.Double.

The distance must be greater than zero and less than or equal to 50 miles. The default unit of measurement for distance is in Miles. Code snippet shown below is a good example of how to use that method:

//Call the find nearby on the current location
MapPoint.FindResults poiResults = location.FindNearby(distance);

As you can see the result is again a FindResults class that encapsulates a collection of locations. You can get the details of the location including the POI category (such as a restaurant or a gas station etc) using the PlaceCategory.

The PlaceCategory class encapsulates a category name and is exposed as PlaceCategory property from the Location class.

To learn more about this topic and other related topics, please buy Programming MapPoint in .NET

Map class has a method, ParseStreetAddress that parses a string into a valid street address represented as the StreetAddress class. The StreetAddress class has the Street, City, OtherCity, PostalCode, Region and Country properties that represent various parts of an address. The Value property of the StreetAddress class gives the full address as one string.

The following code shows how to parse a string into a valid address:

//Create an instance of the MapPoint application class
MapPoint.ApplicationClass app = new MapPoint.ApplicationClass();
//Get the Map object from the application object
MapPoint.Map map = app.ActiveMap;
//Parse the address
MapPoint.StreetAddress address =
map.ParseStreetAddress("498 Broad St, Seattle, WA, 98109");

//Now get the values from the
//StreetAddress properties
string streetName = address.Street;
string city = address.City;

To learn more about this topic and other related topics, please buy Programming MapPoint in .NET

The Location class has the DistanceTo method that calculates the distance to a given location. Keep in mind that the distance calculated using this method is not the same as the driving distance; this method only gives you an along-the-straight-line-distance (or “as the crow flies”) between the two locations.

The DistanceTo method takes another location as an argument; the following code shows how to calculate distance between two locations:

//Get the from location
MapPoint.Location fromLocation
= this.findResults.get_Item(ref fromIndex) as MapPoint.Location;
//Get the to location
MapPoint.Location toLocation
= poiResults.get_Item(ref poiIndex) as MapPoint.Location;
//Calculate the distance between the from location and
//to location using the DistanceTo method
double distance = fromLocation.DistanceTo(toLocation);

Another way of calculating the distance between two locations is to call the Distance method on active Map object as shown below:

double distance = app.ActiveMap.Distance(startLocation, endLocation);

Both startLocation and endLocation are of MapPoint.Location type objects.

To learn more about this topic and other related topics, please buy Programming MapPoint in .NET

You can build visual Map based applications in Windows environment using MapPoint ActiveX Control. When you drag and drop the MapPoint control on to your Windows form, the reference to the MapPoint interoperable assembly is automatically added to your project along with the control.

The drag and drop operation also creates and adds an instance of MapPoint control to your code file, as shown below:

private AxMapPoint.AxMappointControl axMappointControl1;

Before you use the AxMappointControl, you need to initialize the control by creating new map coverage. You do this by calling the NewMap method on the AxMappointControl class. This method takes the map region of type GeoMapRegion enumeration as an argument. There are two valid region values for the map region in MapPoint: GeoMapRegion.geoMapNorthAmerica for North American maps and GeoMapRegion.geoMapEurope for European maps.

The following code shows initializing the control to show the North American map:

axMappointControl1.NewMap(MapPoint.GeoMapRegion.geoMapNorthAmerica);

After initializing the map control, you can access the map object via the ActiveMap property, as shown below:

MapPoint.Map map = axMappointControl1.ActiveMap;

Once you have the map object, you can find and navigate to a specific location as shown below:

//Define a location instance
MapPoint.Location currentLocation = null;
//Get the current location from FindResults method
...
currentLocation = findResults.get_Item(ref index);

//Go to the current location on the map
currentLocation.GoTo();

Calling the GoTo method zooms in to the location with best possible view on the map and centers the map on that location.

To learn more about this topic and other related topics, please buy Programming MapPoint in .NET

A pushpin in MapPoint is represented by the Pushpin class. The Name property of a Pushpin object can be used to annotate the Pushpin. You can also add notes to the Pushpin using the Pushpin.Notes property.

A Pushpin is essentially symbol (icon) on the map; MapPoint provides a number of symbols to be used with Pushpins. These symbols are indexed and their number should be used to indicate the symbol of a given Pushpin; For example the default symbol is black pushpin represented by the number 0. The valid range for the standard symbols is 0-255.

To add a pushpin to a location, you just have to call the Map.AddPushpin method, as shown below:

//Get map center location
MapPoint.Location location = axMappointControl1.ActiveMap.Location;
//Add a pushpin at this location
MapPoint.Pushpin pushpin = axMappointControl1.ActiveMap.AddPushpin(
location, "Center");
//Assign a symbol
pushpin.Symbol = 64;
//Select and highlight the location
pushpin.Select();
pushpin.Highlight = true;
//Write annotation
pushpin.Note = "This is my favorite place!";

Now if you want to open the “info window” for the pushpin, you can use the Pushpin.BallonState enumeration.

To learn more about this topic and other related topics, please buy Programming MapPoint in .NET

The MapPoint ActiveX Control provides you with a fully interactive map to perform actions such as panning, zooming and tracking mouse clicks and so on.

To pan a map you would use Map.Pan method. This method takes two arguments:
1. PanDirection: Indicates the direction of the pan operation; this property is of type MapPoint.GeoPanCmd enumeration. This enumeration contains values that represent directional values such as east, west, north, south, north-east and so on.
2. PanFactor: Indicates amount of pan. Even though there are no limits to the pan factor, you have to keep in mind that this value is dependent on the altitude of your map. To give you an idea of what I mean, at 1 mile (lower altitudes), a pan factor of 1 pans the map by 0.2 miles, but the same pan factor at 50 miles (a higher altitude) pans the map by 10 miles!

The following code shows how to call the Pan method:

axMappointControl1.ActiveMap.Pan(MapPoint.GeoPanCmd.geoWest, 1);

To learn more about this topic and other related topics, please buy Programming MapPoint in .NET

MapPoint ActiveX Control offers two methods to perform zoom operations on the maps.

1.ZoomIn method – This method zooms the map view closer by reducing the map altitude
2.ZoomOut method – This methods zooms the map view farther by increasing the map altitude

These two methods zoom in/out in steps. There are ten levels of zoom effect that you can achieve using these two methods. The levels are defined based on the map altitude and each time when you call zoom methods, map’s altitude is modified accordingly and re-rendered to show the map at that altitude.
The following code shows how to call a ZoomIn method:

axMappointControl1.ActiveMap.ZoomIn();

Now, if you want to zoom into a particular level from your current view, say, you want to zoom to street level directly without calling ZoomIn method multiple times, you can do that by modifying the map altitude, as shown below:

//Zoom directly into Street Level by setting 3 mile altitude
axMappointControl1.ActiveMap.Altitude = 3;

To learn more about this topic and other related topics, please buy Programming MapPoint in .NET

If you want to process user’s interaction with maps in MapPoint ActiveX Control, you need to know when and where a mouse is clicked to obtain the location corresponding to a mouse click.
The Map object provides a way to convert a location on the map to a point on the screen. By using Map object’s LocationToX and LocationToY methods, you can obtain X and Y coordinates for any given location.

You need to make separate calls for each X and Y coordinate for any given location, as shown below:

//Get the center of the map
MapPoint.Location location = axMappointControl1.ActiveMap.Location;
//Get x and y coordinates
int x = axMappointControl1.ActiveMap.LocationToX(location);
int y = axMappointControl1.ActiveMap.LocationToY(location);
//Display the center coordinates
MessageBox.Show(String.Format("Map is centered at ({0}, {1})",
x.ToString(), y.ToString()));

Keep in mind that the LocationToX and LocationToY methods assume that a particular location is on the current map screen limits; if the location is not present in the ActiveX Control map screen limits, these methods fail. To avoid errors in a case like this, it’s always a good idea to use Location.GoTo() method before getting the coordinates.

To learn more about this topic and other related topics, please buy Programming MapPoint in .NET