Integrating MapPoint in your .NET applications

• MapPoint project - 23.6 Kb

Introduction

The MapPoint technology by Microsoft provides a programmable web service, used by enterprises and independent software developers to integrate location-based services such as maps, driving directions and proximity searches into software applications and business processes.

MapPoint web services API

MapPoint web service is an XML web service with a SOAP API that is comprised of four constituent services: finding locations, creating routes, rendering maps, and a set of utility function objects and methods that are common to the previous three. To call the service in your application, you need to reference the MapPoint Web Service Description Language (WSDL).

Registering for MapPoint developer account

Before you start development with the MapPoint web service API, you need to register for a MapPoint Web Service Developer trial account with Microsoft from this URL.

Once you apply for registration, you get an email from Microsoft saying that they would process your application and activate your trial account within 1-2 business days. Once your account gets approved, you will have access to the 'Extranet portal site' and the 'MapPoint Web Service Customer Services site' and you can start developing your solutions using the MapPoint web service API.

Downloading and setting up the MapPoint SDK

Once you have registered for the MapPoint Web Service account, you can download the MapPoint SDK from this URL.

To develop applications using the MapPoint SDK, you would require Visual Studio .NET to be installed in your machine. After the downloading is completed, install the SDK. The MapPoint SDK help gets integrated with your Visual Studio .NET help documentation. There are a lots of sample applications that are provided with the SDK (C# & VB.NET) which you can study for better understanding of the API.

Referencing the MapPoint Web Service WSDL

The web-service description document (mappoint.wsdl) is an XML document that defines the format of messages in use by MapPoint web service. Your development project must reference the 'mappoint.wsdl' to access the MapPoint Web Service SOAP API.

You can reference the WSDL using either standard http:// or https:// protocol. There are two 'mappoint.wsdl' files: one for staging and one for production. You can access these files using standard or secure HTTP:

Staging

• http://staging.mappoint.net/standard-30/mappoint.wsdl
• https://staging.mappoint.net/secure-30/mappoint.wsdl

Production

• http://service.mappoint.net/standard-30/mappoint.wsdl
• https://service.mappoint.net/secure-30/mappoint.wsdl

Note: Your developer trial account has access only to the staging 'mappoint.wsdl'.

Our MapPoint application

Our C# Windows application would use the MapPoint Web Service API to calculate the route/driving directions between two places (e.g. cities) and generate a map showing you the same. For example, if you want to reach London from Paris, our application would give you the driving directions starting from Paris and ending in London. It would be something like this:

(1) Depart Paris on Local road(s) (South-East) >> 
(2) Turn LEFT (North) onto Voirie Souterraine des Halles >> 
(3) Road name changes to Local road(s) >> 
(4) Bear RIGHT (East) onto Rue de Turbigo, then immediately bear 
    RIGHT (East) onto Rue Étienne Marcel >> 
(5) Turn LEFT (North) onto Boulevard de Sébastopol >>
(6) Road name changes to Boulevard de Strasbourg >>

The following are the main MapPoint classes that would be used in our application:

• FindServiceSoap class

  The FindServiceSoap service has several methods that deal with finding addresses and related information.

• RenderServiceSoap class

  The RenderServiceSoap service is used to work with maps.

• RouteSpecification class

  Contains all the information necessary to describe a route, including the array of route segments that make up a route, the data source, the driver profile, and an indication of whether driving directions and the calculated route representation (used for rendering a highlighted route on a map) should be included in a route.

• MapSpecification class

  Contains the specifications for rendering a map. Includes the data source to use, map views, pushpins, route, selected entities, and map options.

• Waypoint class

  Contains the start point, intermediate stops or end point of a route. Includes the requested location, name, snap type (an attribute that changes the way a waypoint functions when a route is created), and calculated location.

• Route class

  Represents a calculated route. Contains the specification of the route, the route itinerary, and a binary representation that can be used to render routes on a map.

• RouteServiceSoap class

  Contains the methods and properties related to calling the route service and obtaining point to point directions.

• CommonServiceSoap class

  The CommonServiceSoap service can be used to look up details that you might use for working with the other MapPoint API methods, such as a list of data sources that can be used in your queries.

Much of the information about the MapPoint classes and methods are described under various topics in the Help documentation.

To start the application development, we need to add reference to the 'mappoint.wsdl' in our project. The following steps show you how to add the web reference and setup the C# project:

1. Open Visual Studio .NET and select File > New > Project.
2. Select Visual C# project as the Project Type and Windows Application as the Template. For the project name, specify 'MapPoint_Demo'; for the path specify the location where you want the project to be created. Click OK to create the new project.
3. Add a reference to the MapPoint API in the staging environment by selecting Project > Add Web Reference. For the URL field, specify http://staging.mappoint.net/standard-30/mappoint.wsdl.
4. Click the GO button to make Visual Studio locate the MapPoint service. Name the Web Reference Name as MapPoint so that you can use a shorter name in your project.
5. Add the controls to the form as shown in figure (fig.1):

   

6. Add a CONFIG file (App.config) to the project and enter the following:
   XML

   <?xml version="1.0" encoding="utf-8" ?>  
   <configuration> 
   <appSettings> 
   
       <add key="MPUser" value="MAPPOINT_ID" /> 
       <add key="MPPass" value="PASSWORD" /> 
   
   </appSettings> 
   </configuration>

   The source code of this project has been supplied in the accompanying CD. Please refer to it as you will need to declare some variables and classes which are not discussed here.

7. Add the following code to the 'btnDirections' button click event handler:
   C#

   private void btnDirections_Click(object sender, EventArgs e)
   {
       //Resets the textbox text and the statusbar text
       txtResults.Text = string.Empty;
       stsMain.Text = string.Empty;
               
       FindSpecification findSpec = new FindSpecification();
               
       FindResults startResults = null;
                  FindResults endResults = null;
               
       //Set the DataSource, i.e. MapPoint.EU for Europe etc.
       findSpec.DataSourceName = cmbZone.Text;
               
       findSpec.InputPlace = txtOrigAddress.Text;
               
       //Retrieve the values of startResults
             try
           {
               startResults = findService.Find(findSpec);
           }
           catch
           {
               MessageBox.Show("Problem connecting with service");
           }
               
               
       findSpec.InputPlace = txtDestAddress.Text;
               
       //Retrieve the values of endResults
           try
           {
               endResults = findService.Find(findSpec);
           }
           catch
           {
               MessageBox.Show("Problem connecting with service");
           }
   
   
       // Make sure findResults isn't null
           if(startResults == null)
           {
               MessageBox.Show("Originating Address not found.");
           }
           else
           {
           // If no results were found, display error and return
               if(startResults.NumberFound == 0)
               {
               MessageBox.Show("Originating Address not found.");
               return;
               }
                   
           }
           if(endResults == null)
           {
               MessageBox.Show("Destination Address not found.");
           }
           else
           {
           // If no results were found, display error and return
               if(endResults.NumberFound == 0)
               {
               MessageBox.Show("Destination Address not found.");
               return;
               }
           }
   
           stsMain.Text = "Generating Route Information";
   
       //Call GetRoute:Calculates the Route and also generates the Map
           GetRoute(startResults,endResults);
   }

8. Add the following GetRoute method:
   C#

   //GetRoute:Calculates the Route and 
   //also generates the Map
   private void GetRoute(FindResults sResults,
                                 FindResults eResults)
   {
       SegmentSpecification[] routeSegment;
       routeSegment = new SegmentSpecification[2];
   
       routeSegment[0]= new SegmentSpecification();
       routeSegment[0].Waypoint = new Waypoint();
       routeSegment[0].Waypoint.Name = 
          sResults.Results[0].FoundLocation.Entity.Name;
       routeSegment[0].Waypoint.Location = 
                      sResults.Results[0].FoundLocation;
   
       routeSegment[1]= new SegmentSpecification();
       routeSegment[1].Waypoint = new Waypoint();
       routeSegment[1].Waypoint.Name = 
          eResults.Results[0].FoundLocation.Entity.Name;
       routeSegment[1].Waypoint.Location = 
                      eResults.Results[0].FoundLocation;
           
   
       RouteSpecification routeSpecs = 
                               new RouteSpecification();
       routeSpecs.DataSourceName = cmbZone.Text;
         routeSpecs.Segments = routeSegment;
   
       //For users who are behind a internet proxy
       //Comment out for direct internet connection
       //WebProxy myProxy = 
               new WebProxy("http://proxyip:80",true);
       //myProxy.Credentials = new NetworkCredential(
                        "username", "password", "domain");
       //        
       RouteServiceSoap routeService = new RouteServiceSoap();
       routeService.Credentials = myCredentials;
       routeService.PreAuthenticate = true;
       // routeService.Proxy = myProxy;
   
       Route route = new Route();
       route = routeService.CalculateRoute(routeSpecs);
   
       stsMain.Text = "Fetching Route Information";
               
       //loop through and write the route 
       //directions in the textbox
       for (int i = 0;
         i < route.Itinerary.Segments[0].Directions.Length;i++)
       {
         txtResults.Text +="("+(i+1)+") "+
           route.Itinerary.Segments[0].Directions[i].Instruction +
           " >> ";
       }
              
       stsMain.Text = "Wait...Generating Map Information";
   
       // Generate the Route Map
       MapSpecification mapSpec = new MapSpecification();
       mapSpec.Options = new MapOptions();
       mapSpec.Options.Format = new ImageFormat();
   
       //Set the map width and height 
       //according to the PictureBox
       mapSpec.Options.Format.Height = pcMap.Height;
       mapSpec.Options.Format.Width = pcMap.Width;
   
       //Set the Map Datasource
       mapSpec.DataSourceName = cmbZone.Text;
               
       mapSpec.Route = route;
               
       try
         {
           // Get the map image
           MapImage tempImage = 
               renderService.GetMap(mapSpec)[0];
           pcMap.Image = new Bitmap(
                 new MemoryStream(tempImage.MimeData.Bits, 
                                              false), true);
               
           stsMain.Text = "Done";
         }
       catch(Exception e)
         {
           MessageBox.Show(e.ToString());
         }
   }

9. Once you have done this, compile and run the application. You will require an active internet connection for the application to run.
10. Select the zone ('MapPoint.EU' stands for Europe and 'MapPoint.NA' stands for North America). Then enter the starting and destination cities (for e.g. Paris and London). Click the 'Get Directions' button. The application will query the MapPoint web service and depending upon the speed of your internet connection, the result i.e. the driving directions will be returned.

    

11. Click on the 'Map' tab. You will see that the Route Map has been generated, the green line showing you the route from Paris to London.
12. You can get the driving/route directions for other cities in Europe and North America by changing the variables (zone, origin and destination addresses).

Currently MapPoint covers North America, Europe and Brazil however other zones would soon be added.

Though our application describes only a part of the functionalities that are being offered by the MapPoint API, other more complex functionalities can be thought of and implemented.

Requisites

• VS.NET 2003
• MapPoint Developer A/c
• C#