Click here to Skip to main content
Click here to Skip to main content

Integrating MapPoint in your .NET applications

By , 2 Oct 2005
Rate this:
Please Sign up or sign in to vote.

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 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:
    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:
    //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#

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here

About the Author

Chayan
Web Developer
India India
Chayan Ray has been working as a Technical Consultant in a CMM level 5 company in India. His technical domain includes ASP.NET, C#, PHP, Perl, Cold Fusion, MySQL and MSSQL 2000.

Comments and Discussions

 
QuestionMy Vote of 5 PinmemberSampath Lokuge16-Jan-14 3:17 
Questioncan help me plz Pinmemberouljhd23-Jun-10 7:53 
GeneralVisual Studio .NET PinmemberMilacs29-Jul-08 0:33 
GeneralVS 2005 VS VS 2003 Pinmembermiqui7725-May-07 5:47 
GeneralRe: VS 2005 VS VS 2003 Pinmembermiqui7725-May-07 5:49 
GeneralRe: VS 2005 VS VS 2003 Pinmembermiqui7728-May-07 20:48 
Questiona question from raghavendra PinstaffSean Ewington6-May-07 18:26 
AnswerRe: a question from raghavendra PinmemberChayan7-May-07 18:44 
QuestionHow can i get vertices data of map Pinmemberkhaleek18-Mar-07 20:39 
GeneralMapPoint without webservice Pinmemberarmax751-Mar-07 6:46 
AnswerRe: MapPoint without webservice PinmemberChayan1-Mar-07 13:59 
GeneralRe: MapPoint without webservice PinmemberAndrew Torrance18-Jul-07 4:40 
QuestionBuilding a GIS using Mappoint?? Pinmembertgrr30-Jan-07 23:00 
Generalstaging vs Production Pinmembermountblanc6-Dec-06 2:55 
GeneralError in running Pinmemberprajith_m_p@yahoo.com21-Sep-06 2:18 
Generalproblem problem Pinmemberronakiram8-Aug-06 20:21 
GeneralRe: problem problem PinmemberChayan9-Aug-06 7:15 
GeneralRe: problem problem Pinmemberronakiram10-Aug-06 20:18 
GeneralRe: problem problem Pinmembermiqui7725-May-07 4:30 
GeneralRe: problem problem PinmemberChayan25-May-07 6:55 
GeneralRe: problem problem Pinmembermiqui7727-May-07 20:51 
Hi,
 
the message is "Root element is missing".
 

GeneralGreat little example Pinmemberjrivero19-Jan-06 11:07 
GeneralRe: Great little example PinmemberRajendranK10-Jan-07 4:39 
QuestionChaning the Country Name in Location Find Dialog Pinmemberrmpandu21-Oct-05 23:41 
AnswerRe: Chaning the Country Name in Location Find Dialog PinmemberChayan22-Oct-05 8:52 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.

| Advertise | Privacy | Mobile
Web03 | 2.8.140415.2 | Last Updated 2 Oct 2005
Article Copyright 2005 by Chayan
Everything else Copyright © CodeProject, 1999-2014
Terms of Use
Layout: fixed | fluid