Programming with the MapPoint Web Service directly can be extremely challenging and comes with a significant learning curve. With this concern in mind, Martin Schray, Central and Western US Academic Developer Evangelism Manager for Microsoft, and I have collaborated on the development of the MapPoint Web Service Helper. Martin has created the MapPoint Web Service Helper Class Library, with ongoing discussions with me about the functionality that it should provide. Meanwhile, I have developed two PowerPoint presentations discussing how this library can be used in developing Visual Basic 2005 Windows and Web applications.

The MapPoint Web Service Helper (we’ll call it the Helper for short) was designed to provide an easy-to-use interface to the MapPoint Web Service that doesn’t require a large learning curve. Many parameters provided by the MapPoint Web Service are hidden from the user, and returns from one method can be used to feed the next. You can find locations, render maps, retrieve driving directions, find points of interest (e.g. ATM, Banks, Gas Stations...) and even get real time traffic information. Especially nice is the fact that you can do these things for Windows, Web, and mobile applications with the Helper. In a nutshell, the Helper significantly simplifies access to the MapPoint Web Service Find, Render, and Route services by providing a simple API with just a few core arguments.

This article is the first of two that will be discussing use of the MapPoint Web Service Helper. In this article we will be discussing how to develop MapPoint Web Service Visual Basic 2005 Windows and Web applications using the Helper. In the second article, which will appear in the near future, we will discuss the development of a Visual Basic 2005 mobile application making use of the Helper that could be deployed on a Pocket PC running Windows Mobile.

Keep in mind that although this article discusses the Helper in the context of Visual Basic 2005 and the Helper was written in C#, the Helper can be used with any of the more than 20 .NET languages currently in existence. All files associated with the Helper library, including the two PowerPoints can be downloaded by going to this link at the Microsoft Academic Resource Center.

The current version of the Helper, completed during spring 2007, provides methods including GetInstance, FindLocation, GetMap, GetMapURL, GetRoute, GetRouteMap, GetRouteMapURL, GetRouteDirections, RouteItineraryToText, FindNearbyPlaces, and GetTrafficIncident. In this article these methods will be gradually introduced in a series of small Visual Basic 2005 applications. The first four applications are Windows applications, while the final one discussed here is a Web application. For each application, the Helper methods required by the application will be described, the Visual Basic code will be provided, and a graphic showing the running application will be displayed. Any Windows or Web applications that make use of the Helper will require adding a reference to MapPointWebServiceProject.dll.

Application 1: Find Location

The first application is a simple application that will find an address, place, or landmark. The methods that are introduced in this application include the following:

• GetInstance method, that creates an instance of the Helper and sets the user ID and password for the MapPoint Web Service
• FindLocation method, that finds an address, place, or landmark
• GetMap method, that returns an image with the location centered on the map.

The figure below shows what this application looks like when running. The user keys the location or place of interest into a textbox and then clicks a button to get a map of the location. Within a few short seconds, the MapPoint Web Service returns a map of the desired location.

The code for this application is shown below. You will note that the user only needs to key in eight lines of code, including two Imports statements, three Dim statements, and three assignment statements. One can sign up for a free MapPoint Web Service Developer account that would provide a userID and password by following this link. Detailed comments in the code explain what the code is doing. An interesting quick extension to this application would be to add buttons to zoom in and to zoom out on the location displayed. Note that in this application and all others discussed in this article, one would probably want to add code to catch exceptions.

Application 2: Get Quickest Route Between Two Locations

This application finds the fastest route between start and end locations, obtains driving directions, and displays a map of the route. Four additional Helper methods are required to code this application:

• GetRoute, that returns a route object between the start and end locations
• GetRouteMap, that returns an image containing an annotated route, with start and end locations identified by blue and red flags, respectively
• GetRouteDirections, that returns step-by-step driving directions from the start point to the end point of the route
• RouteItineraryToText, that copies the driving directions into an array.

The figure below shows what this application looks like when running. The user keys the start and end locations into textboxes and then clicks a button to get the route. The MapPoint Web Service returns a map showing the route highlighted in green, with the start location shown by a blue flag, and the end location shown by a red flag. Also returned is a set of driving instructions.

The code for this application is shown below. It boils down to two Imports statements, five Dim statements, and nine additional lines of code, six of which are calls to Helper methods.

Application 3: Finding Nearby Points-of-Interest

This application allows one to specify an address and then find nearby gas stations within a specified search radius. This application provides a route map and driving directions from the address to a selected gas station from the list of those nearby. The additional Helper method that is introduced is FindNearbyPlaces, which allows one to find nearby places from any of the categories (e.g., gas stations, food, lodging, etc.) in the NavTech.NA data source as well as data sources created by MapPoint customers and uploaded to the MapPoint Web Server.

The figure below shows what this application looks like when running. The user keys in a location and then clicks the button to get nearby gas stations. The list of nearby gas stations is then returned by the MapPoint Web Service. The user can then select a gas station from the list and click the button to get the map and directions to the selected gas station. The MapPoint Web Service finally returns a route map from the location to the selected station as well as a set of driving instructions.

The code for this application is shown below. As was done in the previously described applications, numerous comments explain in detail what the code is accomplishing.

It should be noted that this third application is easily adaptable to becoming a simple store locator. A MapPoint Web Service customer can upload a file containing a company's store locations to the MapPoint Web Service. This file can then be used as the data source of nearby points-of-interest in this application instead of the NavTech.NA data source. The user of the application could be asked to supply his/her location and a search radius. The button to "Find Nearby Gas Stations" would become a button to "Find Nearby Stores". The button to "Get Map and Directions to the Selected Gas Station" would become a button to "Get Map and Directions to Selected Store".

Application 4: Get Traffic Incidents

The final Visual Basic 2005 Windows application that will be discussed is a slight extension of Application 2 discussed previously. Application 4 determines not only a route and directions between two locations, but also obtains a list of traffic incidents along with their severity within a specified distance of the route. The only new method that is introduced in this application is the GetTrafficIncidents method. This method has two input parameters--a Route object and a double indicating the specified distance from the route for which traffic incidents are desired. This method returns a FindResults collection. Property 0 is the address/intersection of the incident while property 1 is its severity. Details on the properties can be found by clicking this link. The figure below shows what this application looks like when running. You will note that in addition to the driving directions, there is also a listbox containing the location and severity for each incident within the specified distance of the route.

The Visual Basic 2005 code for this application, replete with comments, is shown below.

Application 5: Web Application to Obtain a Route Map

Two methods are included in the Helper that allow the easy development of Web applications. GetMapURL returns the URL of an image representation of a location to displayed in a Web page. This method has four input parameters: a location object specifying the location whose map is desired, an integer specifying the pixel width of the desired image, an integer specifying the pixel height of the desired image, and a double specifying the zoom factor. The URL returned can be assigned to the ImageURL property of an Image control.

GetRouteMapURL returns the URL of an image representation of a route to be displayed in a Web page. The start and end locations are shown with blue and red flags, respectively, and the route is highlighted from start to end. Input parameters for GetRouteMapURL include a route object and two integers specifying the pixel width and height of the desired map. The figure below shows what Internet Explorer would look like when running a simply Web application, after finding the quickest route from start to end locations specified by the browser user.

The code for this Web application is shown below. In consists of the usual two Imports statements, three Dim statements, and five assignment statements.

	MP2Kmag Internet