Getting Started with MapPoint Web Service using .NET Compact Framework

• Download source - 22.5 Kb

This is an entry for the CodeProject CF article competition

Introduction

Distributed Computing, Mobile Applications and Web Services are buzz words of IT industry. Very sophisticated Mobile devices like Smart Phones and Pocket PCs are being used more and more by people with various needs. XML and Web Services have become a standard in Distributed Computing. Developers nowadays are taking much interest in writing applications that target mobile applications and due to many reasons they cannot ignore Web Services while developing such applications.

This article/code demonstrates the use of a Web Service (MapPoint) and .NET Compact Framework. It is assumed that reader will have a basic understanding of .NET Compact Framework but an introduction to the MapPoint Web Service will be given.

MapPoint

Microsoft MapPoint Web Service is an XML Web service with a SOAP API that allows you to add location-based functionality to your application that calls on the high-quality maps, as well as the location-finding and routing capabilities of MapPoint Web Service. MapPoint Web Service is comprised of four constituent services: common, find, render, and route. This section provides an overview of each of these services and also the classes and methods that I have used in my code. I will explain everything that you need to get started with MapPoint but for more comprehensive discussion on MapPoint read MapPoint SDK.

Common Service

The common service contains classes, methods, and properties that are common to the find, route, and render services, or are basic utility functions.

• Address Class contains the constituent parts of an address: street, city, other city, region, country, and postal code.

Find Service

The find service allows you to locate addresses, geographic entities, latitude and longitude coordinates, and points of interest from MapPoint Web Service data, as well as parse addresses and return location information for a specified latitude and longitude coordinate.

• FindServiceSoap Class contains the methods and properties related to calling the find service.
• FindAddress Method returns a list of found addresses based on an input address, in order of how well the results match the search criteria.
• FindAddressSpecification Class contains the search specification used in the FindServiceSoap.FindAddress method. Specifies the address to find, the search options to use, and the data source from which to get results.

Render Service

The render service allows you to render maps of routes and found locations, place pushpins, set the map size and map view, select points on a map, get location information about points on a map, pan and zoom a rendered map, and create clickable maps.

• RenderServiceSoap Class contains the methods and properties related to calling the render service.
• MapSpecification Class contains the specifications for rendering a map. Includes the data source to use, map views, pushpins, route, selected entities, and map options.
• GetMap Method returns map images, map views, and hot area definitions based on map options.
• GetBestMapView Method returns the best map view for a selected location or set of locations. The best map view is the largest scale map that contains all the desired locations.
• MapOptions Class contains the map rendering options used in the RenderServiceSoap.GetMap method. Specifies the the data source, the image format, panning and zooming factors, and identification of the requested map as an overview map.
• Pushpin Class contains the icon, label, location, and user-defined identification number of a pushpin. A Pushpin object is used to mark a location on a map image, and the location can be a place, address, or latitude and longitude coordinate.
• MapView Class is an abstract class representing a requested map view. Each of the derived classes defines a map view using a different measure: a set of location points, a bounding rectangle, height and width, or scale.
• MapImage Class contains a map returned from the RenderServiceSoap.GetMap method. Includes the image or a URL to get the image, map view representations, and the hot areas associated with pushpins.

Route Service

The route service allows you to generate routes, driving directions, and calculated route representations based on locations or waypoints, set segment and route preferences, and generate map views of segments and directions.

• RouteServiceSoap Class contains the methods and properties related to calling the route service.
• Route Class contains a route of two waypoints (start and end points). A Route can include a specification, a set of directions, and/or a calculated route representation.
• CalculateSimpleRoute Method returns a route based on specified latitude and longitude coordinates.

Getting MapPoint

To use MapPoint you will need

• MapPoint SDK.
• Evaluation Account.

Using the code

Enough theory now let's gets started with the coding. Two things make up the basic functionality of MapPoint.

1. Find an Address.
2. Display its Map.

Two methods MakeAddress and MakeMap that are given below encapsulates the process of finding an address and displaying its map which are THE steps that gets you started. Each method is followed by description of series of steps performed in the method.

Following code shows the variables global to the form.

//Variables used by FindAddress and MakeMap methods.
private ViewByHeightWidth[]  views = null;
private FindResults foundAddressResults;
private LatLong[] latlongs = null;
private System.Drawing.Bitmap[] m_Maps;
private int Position=0;

MakeAddress Method

private void MakeAddress()
{
  //Step 1
  FindServiceSoap findService = new FindServiceSoap();
  Address myAddress =  new Address();
  FindAddressSpecification findAddressSpec =
    new FindAddressSpecification();

  //Step 2
  findService.Credentials = new System.Net.NetworkCredential(
    myUserName,myPassword);
  findService.PreAuthenticate = true;

  //Step 3
  myAddress.AddressLine = txtAddress.Text;
  myAddress.PrimaryCity = txtCity.Text;
  myAddress.PostalCode = txtPostCode.Text;
  myAddress.CountryRegion = "UK";

  //Step 4
  findAddressSpec.DataSourceName = "MapPoint.EU";
   findAddressSpec.InputAddress = myAddress;

  //Step 5
  foundAddressResults = findService.FindAddress(findAddressSpec);

  //Step 6
  views = new ViewByHeightWidth[1];
  views[0] = foundAddressResults.Results[0].
       FoundLocation.BestMapView.ByHeightWidth;
}

Following steps describes MakeAddress method that corresponds with the steps in code.

1. Declare variables to be used in this method.
2. To use MapPoint you will need a username and password (see Getting MapPoint). I used these to make credentials of FindServiceSoap Class to authenticate before using any method of this class.
3. myAddress variable holds the address information.
4. DataSourceName property of FindAddressSpecification class holds one of many data sources where MapPoint Web Service is located. MapPoint.EU shows that we will be searching an address somewhere in Europe. We then attach the Address to the InputAddress property.
5. Finally FindAddress method is called passing address specification, which returns the FindResults collection.
6. From this collection we retrieve a MapView object which will be used later on to make a map.

In short we made an object to hold address, then made an object to hold specification for that address, using that specification searched the address and got a view of the address.

MakeMap Method

private void MakeMap()
  {
    //Step 1
    RenderServiceSoap renderService  = new RenderServiceSoap();
    Pushpin[] pushpins = new Pushpin[1];
    MapSpecification mapSpec  = new MapSpecification();

    //Step 2
    renderService.Credentials = 
       new System.Net.NetworkCredential(myUserName,myPassword);
    renderService.PreAuthenticate = true;
    
    //Step 3
    pushpins[0] = new Pushpin();
    pushpins[0].IconDataSource = "MapPoint.Icons";
    pushpins[0].IconName = "0";
    pushpins[0].Label = foundAddressResults.Results[0].FoundLocation.Entity.Name;
    pushpins[0].LatLong = views[0].CenterPoint;
    pushpins[0].ReturnsHotArea = true;

    //Step 4
    mapSpec.DataSourceName = "MapPoint.EU";
    mapSpec.Views = views;  
    mapSpec.Pushpins = pushpins;
    mapSpec.Options = new MapOptions();    
    mapSpec.Options.Format = new ImageFormat();
    mapSpec.Options.Format.Width = pbMap.Width;
    mapSpec.Options.Format.Height = pbMap.Height;

    //Step 5
    MapImage[] mapImages = renderService.GetMap(mapSpec);  
    System.IO.Stream streamImage = 
       new System.IO.MemoryStream(mapImages[0].MimeData.Bits);
    Bitmap bitmapImage = new Bitmap(streamImage);
    pbMap.Image= bitmapImage;    
  }

Following steps describes MakeMap method that corresponds with the steps in code.

1. Declare variables to be used in this method.
2. To use MapPoint you will need a username and password (see Getting MapPoint). I used these to make credentials of RenderServiceSoap Class to authenticate before using any method of this class.
3. Create a Pushpin object that will show (on map) the address we are searching.
4. Creating a MapSpecification object that will hold DataSource, Pushpin, MapView and Format options for the map.
5. Finally calling the GetMap method and retrieving the map. An array of MapImage class is returned. In our case we will use the first element of the array to form a bitmap and display in a Picture Box.

In short we made an object to hold pushpin, and then constructed map specification and finally using this specification obtained a map.

Conclusion

This article demonstrates the basics of MapPoint Web Service. The ZIP file contains the source code for the complete application that also shows how to find a route between two addresses using MapPoint.

References

• MSDN