Finding your way with MapPoint

Need to put a mapping data in your application? Microsoft’s first commercial Web service may just be the solution you are looking for.

This year at TechEd, Microsoft launched MapPoint Web services with data for Australia. This brings the total number of countries supported to 25. Being a self-confessed map nerd I was involved in this launch, presenting some demos of MapPoint technology. For me maps work best on mobile devices, such as Pocket PC’s and they work really well on the Tablet PC. That is of course what I was demonstrating.

Sign Up
In order to get started using the MapPoint Web Service you will need developer credentials. These credentials let you log onto the web service and make method calls to retrieve the maps and map data. The king of MapPoint blogs Chandu Thotahas a great 5 step plan to help you get your MapPoint credentials.

Chandu’s Easy Steps to MapPoint developer credentials

1. If you have MSDN Universal subscription, follow these steps to get free access to the MapPoint Web Service for a year!
   1. Go to http://www.microsoft.com/mappoint/msdn/msdnspec.aspx.
      
   2. Login to the MSDN subscriber’s page and fill in the information and submit the form.
2. If you don’t MSDN Universal subscription, don’t worry! You still can get access to the MapPoint Web Service for free for 45 days. Follow the steps below:
   1. Go to https://s.microsoft.com/mappoint/enterprise/webservice/seval.aspx.
   2. Fill in the information and submit the form.
3. Then you will receive an email with an account id and password to access the MapPoint Web Service.
4. Along with the MapPoint Web Service information you will also receive credentials to access MapPoint extranet site. You can think of the MapPoint extranet as a dashboard to manage your MapPoint Web Service settings and environment. For example, if you want to change your password or if you want to upload your own points of interest, or create your own icons you have to use the extranet.
5. Finally, if you are in the process of developing your MapPoint Web Service Solution, you can request the extension of your account by sending an email to mailto:mpnet@microsoft.com.

Getting Going
Once you have your credentials you can get started with developing a client application that can consume the Web service and display maps. I have put together a hands-on-exercise that you can follow to get a simple Windows Form client that will display a map of a location and a route. This exercise assumes you have Visual Studio.NET, however because MapPoint is a Web service you don’t need to develop a solution with .NET at all.

1. Create a new C# Windows Application project called MapPointDownUnder, figure 1.
   
   

   Figure 1: Create a new project

   
   
   
   
2. In solution explorer right click on the references folder and select ‘Add Web Reference..’ from the popup menu. In the Add Web Reference dialog that pops up point the URL to the MapPoint staging server, http://staging.mappoint.net/standard-30/mappoint.wsdl. This is the Web service you should develop against. When your application is ready to go live you can move the reference to the Web service to the production server. We’ll leave the other details as they appear by default, figure 2.
   
   

   Figure 2: Add Web Reference

   
   
   
   
3. Now let's add a user interface to our Windows Form. We will add a Label, TextBox, PictureBox and Button as shown in figure 3. Name the TextBox, PictureBox and Button; postcode, mapBox and showMapButton, respectively.

   Figure 3: Add controls to the form

   
   
   
   
4. At the top of the Form1.cs file add 2 using clauses to reference the System.NET and Web Service namespaces.
   
   using System.Net; using MapPointDownUnder.net.mappoint.staging;
   
   
5. Double click on the showMapButton in the design view to generate the button click event handler. We can now put code in here to get the map and draw it in our mapBox control.

private void showMapButton_Click(object sender, System.EventArgs e) { string userID = @"<username>"; string password = @"<password>"; NetworkCredential creds = new NetworkCredential(userID, password); FindAddressSpecification findAddrSpec = new FindAddressSpecification(); findAddrSpec.InputAddress = new Address(); findAddrSpec.InputAddress.PostalCode = postcode.Text; findAddrSpec.InputAddress.CountryRegion = "Australia"; findAddrSpec.DataSourceName = "MapPoint.AP"; FindServiceSoap findService = new FindServiceSoap(); findService.Credentials = creds; findService.PreAuthenticate = true; FindResults foundAddrResults; foundAddrResults = findService.FindAddress(findAddrSpec); if (foundAddrResults.NumberFound < 1) { MessageBox.Show("Sorry no map found"); return; } MapSpecification mapSpec = new MapSpecification(); mapSpec.DataSourceName = "MapPoint.AP"; ViewByScale[] views = new ViewByScale[1]; views [0] = new ViewByScale(); mapSpec.Views = views; views[0].CenterPoint = foundAddrResults.Results[0].FoundLocation.LatLong; mapSpec.Options = new MapOptions(); mapSpec.Options.Format = new ImageFormat(); mapSpec.Options.Format.Height = mapBox.Height; mapSpec.Options.Format.Width = mapBox.Width; mapSpec.Options.Zoom = 10; MapImage[] mapImages; RenderServiceSoap rs = new RenderServiceSoap(); rs.Credentials = creds; rs.PreAuthenticate = true; mapImages = rs.GetMap (mapSpec); mapBox.Image = new Bitmap (new System.IO.MemoryStream (mapImages[0].MimeData.Bits)); }

Let’s review this function
Firstly we set up the credentials to allow us to access the MapPoint Web service. You’ll need to put your own username and password in the string variables at the top of the function. These will be the same username and password you get sent when you sign up for MapPoint credentials.

Next we use the MapPoint Web Service to find the location of the postcode entered in the text box on the form. The DataSourceName we use is MapPoint.AP for Asia Pacific. If no results are returned from the search then we inform the user via a message box and return from the function.

Finally we set up an instance of a MapSpecification class with the location of the first result returned. We use this MapSpecification object to retrieve a map from the Web Service that we can then render in the PictureBox control.

6. Compile and run the program. Enter an Australian postcode into the TextBox and click the Button. The function we just wrote will run and retrieve a map from the Web Service. The map is display with the center point of the postcode displayed in the middle of the map as seen in Figure 4. This is too easy!

Figure 4: Our First Map

Take me there
We will enhance this example by calculating a route from one postcode to another and drawing the route on our map.

1. Firstly let’s add some controls to our Windows Form. Add a Label, a TextBox and a Button, as shown in figure 5. Name the TextBox destination and name the Button showRouteButton.

   Figure 5: Add route controls

   
   
2. Double click on the showRouteButton to generate the event handler code for the button click event. In here we will add the code to get a map with the route from the postcode to the destination.

3. Before we get to the code that calculates the route we are going to extract a method from the showMapButton click event to find the LatLong of a postcode. We will need this code to calculate a route, as the Web Service requires the route to be defined as a collection of LatLong objects.

   private LatLong GetLatLongOfPostcode( NetworkCredential creds, string postcode) { LatLong result = null; FindAddressSpecification findAddrSpec = new FindAddressSpecification(); findAddrSpec.InputAddress = new Address(); findAddrSpec.InputAddress.PostalCode = postcode; findAddrSpec.InputAddress.CountryRegion = "Australia"; findAddrSpec.DataSourceName = "MapPoint.AP"; FindServiceSoap findService = new FindServiceSoap(); findService.Credentials = creds; findService.PreAuthenticate = true; FindResults foundAddrResults; foundAddrResults = findService.FindAddress(findAddrSpec); if (foundAddrResults.NumberFound > 0) { result = foundAddrResults.Results[0].FoundLocation.LatLong; } return result; }

4. The showMapButton method should now look like this.

   private void showMapButton_Click(object sender, System.EventArgs e) { string userID = @"<username>; string password = @"<password>"; NetworkCredential creds = new NetworkCredential(userID, password); LatLong latLong = GetLatLongOfPostcode(creds, postcode.Text); if (null == latLong) { MessageBox.Show("Sorry no map found"); return; } MapSpecification mapSpec = new MapSpecification(); mapSpec.DataSourceName = "MapPoint.AP"; ViewByScale[] views = new ViewByScale[1]; views [0] = new ViewByScale (); mapSpec.Views = views; views[0].CenterPoint = latLong; mapSpec.Options = new MapOptions(); mapSpec.Options.Format = new ImageFormat(); mapSpec.Options.Format.Height = mapBox.Height; mapSpec.Options.Format.Width = mapBox.Width; mapSpec.Options.Zoom = 10; MapImage[] mapImages ; RenderServiceSoap renderServ = new RenderServiceSoap(); renderServ.Credentials = creds; renderServ.PreAuthenticate = true; mapImages = renderServ.GetMap(mapSpec); mapBox.Image = new Bitmap (new System.IO.MemoryStream (mapImages[0].MimeData.Bits)); }

5. We can now get the LatLong of the two postcodes and use them to calculate a route. In the showRouteButton_click method add the following code.

   private void showRouteButton_Click(object sender, System.EventArgs e) { string userID = @"<username>"; string password = @"<password>"; NetworkCredential creds = new NetworkCredential(userID, password); LatLong[] points = new LatLong[2]; points[0] = GetLatLongOfPostcode(creds, postcode.Text); points[1] = GetLatLongOfPostcode(creds, destination.Text); RouteServiceSoap routeServ = new RouteServiceSoap(); routeServ.Credentials = creds; routeServ.PreAuthenticate = true; Route route = routeServ.CalculateSimpleRoute(points, "MapPoint.AP", SegmentPreference.Quickest); MapSpecification mapSpec = new MapSpecification(); mapSpec.DataSourceName = "MapPoint.AP"; mapSpec.Options = new MapOptions(); mapSpec.Options.Format = new ImageFormat(); mapSpec.Options.Format.Height = mapBox.Height; mapSpec.Options.Format.Width = mapBox.Width; mapSpec.Route = route; MapImage[] mapImages; RenderServiceSoap renderServ = new RenderServiceSoap(); renderServ.Credentials = creds; renderServ.PreAuthenticate = true; mapImages = renderServ.GetMap(mapSpec); mapBox.Image = new Bitmap (new System.IO.MemoryStream (mapImages[0].MimeData.Bits)); }

   In this method we get the LatLong for the beginning and end points of the route. These LatLong objects are placed in our points array. We use the points array in the CalculateSimpleRoute method on the RouteService provided by the MapPoint Web Service.

   We then can get a map as before but this time passing in the route to be displayed.

6. Compile and run the code. You should now be able to display routes from one postcode to another as shown in Figure 6. That was pretty easy too!

   Figure 6: Displaying our First Route

   
   

   In 12 simple steps we have created an application that draws the map of a postcode and calculates and draws a route between two postcodes in Australia.

   For a large number of basic GIS needs the MapPoint Web Service provides a quick way to get mapping data in your application.