Explore Methods and Classes in the MapPoint Web Service API

Explore Methods and Classes in the MapPoint Web Service API

n “Intro to the World of Mapping and Location-based Services“, we provided an overview of MapPoint Web Service and MLS, and covered the subscription model that Microsoft offers for using the service.

Now let’s now dig into Microsoft’s SDK for the MapPoint Web Service itself. (Read “Getting the MapPoint Web Service SDK” sidebar for information and platform requirements for downloading and installing the SDK.)

Getting the MapPoint Web Service SDK
Read on…

Let’s review. The MapPoint Web Service provides your applications with powerful server-based mapping, including street-level address lookups, point-to-point directions, and other features that you’ve become accustomed to on many mapping or retail portals. Want to provide customers with turn-by-turn instructions on how to drive to your closest store, or present your managers with a map of all their customers within a specific geography? MapPoint Web Services makes it easy to add those functions to your Windows/.NET, J2EE or other application using XML Web Services hosted by Microsoft.

The brand-new MapPoint Location Server, or MLS, adds real-time position feeds into your applications. MLS is a server application that runs within your own data center, and which can be configured to provide real-time tracking of cellular phones and other devices owned by your company, or which (with their explicit permission) are used by your employees. That location information can be coordinated with MapPoint Web Services to provide mobile employees with remote information that’s customized to their exact location, or to provide other employees within the enterprise with data about their current position, within the bounds of strongly enforced privacy policies and security systems.

Imagine the implications of using MLS and MapPoint Web Services for fleet management, asset tracking, technical support, emergency communication, help-desk service, travel management and other business productivity applications. Making the MLS work is Microsoft’s partnership with top-tier cellular and wireless carriers, who have worked to develop protocols?hidden behind XML Web services transactions?that allow location data to be passed safely and securely between a wireless device, its local radio-frequency base station, and your enterprise implementation of the MapPoint Location Server.

Licensing the MapPoint Web Service
Before using the MapPoint Web Service SDK, you need to subscribe to the Microsoft service itself. A development license provides a username and password for access to a special Microsoft staging server. Once the application is built and has passed your own functional tests, you’ll need to a production license from Microsoft. That license provides your deployed application’s SOAP calls with access to the MapPoint Web Service production server.

Read on…

The production license is priced with an annual fee, plus transaction charges that apply to many of the specific API methods. Those transactions are purchased in “buckets”; when you use up a bucket, you’ll need to get it refilled, in a similar way to using up all the minutes in a pre-paid telephone calling card.

Now’s a great time to get started with MapPoint Web Service, by the way, because Microsoft is offering a special promotion for its MSDN subscribers: a full year of access to both the staging and production servers, plus a starter bucket of 50,000 production transactions – free of charge. Read more about this offer here.

Up and Running
The MapPoint Web Service consists of a SOAP (Simple Object Access Protocol) API, which contains five core services, each of which has a number of methods. Those services configure the Web service, locate addresses and points of interest, render maps, determine point-to-point routes and leverage customer-specific database. Each method passes and returns XML data as its parameters.

In order to get a good feel for the richness of the MapPoint Web Service API, look at Microsoft’s chart of its object model. I hope you have a big monitor, since even on my double-headed 17-inch LCD setup, the text shrinks to invisibility if you try to show the entire API at one time. (By my count, there are 66 separate classes within the MapPoint Web Service 3.5 API, and hundreds of separate properties and enumerations.)

Figure 1: You’ll need a big monitor to see all the details of the MapPoint Web Service object model.

Common Services
The MapPoint Web Service contains five Common Services which provides utility classes, methods and properties that you’ll use with all MapPoint Web Service transactions. The most interesting, from my perspective, is GetGreatCircleDistances, which returns an array of great circle distances, in kilometers or miles, between specified points.

The other Common Services are GetCountryRegionInfo, which returns the country or region name, entity ID, latitude and longitude coordinates, codes, and language for a specified entity; GetDataSourceInfo, which returns the functionality and name of a specified data source; GetEntityTypes, which returns the entity types and their corresponding properties contained in a specified data source; and GetVersionInfo, which provides the descriptive name and the related version number of the current version of the MapPoint Web Service.

Find Service
The Find Service allows you to translate between addresses and latitude/longitude, as well as look up well-known points of interest or business locations. There are eight specific methods to this service. The core ones are GetLocationInfo, which returns a list of addresses and geographic entities at a specified latitude and longitude, and Find, which returns a list of found geographic entities based on search options.

You’ll also likely use ParseAddress and FindAddress often. The first one parses a specified address string (entered in normal text format, such as 1600 Pennsylvania Avenue, Washington, D.C.) and returns an Address object. FindAddress returns a list of found addresses based on an input address, in order of how well the results match the search criteria.

Less frequently used will be FindByID, which returns a list of found points of interest based on entity Ids; FindByProperty, which returns a list of points of interest based on entity property values; FindNearby, which returns a list of found points of interest based on entity type, in order of proximity to a selected point, and FindNearRoute, which returns a list of points of interest based on entity type within a specified distance from a route.

Figure 2: There are dozens of different map formats available through the Render Service.

Render Service
The Render Service contains four methods that specify and retrieve map images based on latitude/longitude, as well as add custom overlays and “push pins” that indicate specific coordinates. As you can expect, these methods provide a wealth of options that you can specify for mapping. A special class, called MapSpecification, provides a way to indicate all of the mapping options for the map’s data source, image format, size and scale, “pushpins” to mark locations, a list of geographic entities to be displayed on that map, and any routes that should also be shown on that map.

The key methods for the Render Server are GetMap, which returns map images, map views, and hot area definitions based on map options, and GetBestMapView, which returns the best map view for a selected location or set of locations. Microsoft defines the best map view as the largest scale map that contains all the desired locations.

This server contains two helper methods. ConvertToLatLong converts pixel coordinates to latitude and longitude coordinates on a specific map, and ConvertToPoint does the opposite, converting latitude and longitude coordinates to pixel coordinates on a specific map. Use these to add interactivity to your maps. For example, they can allow you to easily see where your users are clicking on a map to indicate a specific point of interest, or to request that the center of the map be repositioned.

Route Service
MapPoint’s route service is perhaps the most computationally intensive, on the Microsoft side, and determines the best path between two points, and coordinates the creation of maps and turn-by-turn directions that follow that path. In many ways, it’s the most interesting to play with, because it’s the most programmatically complicated. There are two similar methods available: CalculateRoute returns a route based on route segments and specifications. CalculateSimpleRoute returns a route based on specified latitude and longitude coordinates for the start and end points.

Figure 3: The Customer Data Service lets you upload your own points of interest to the MapPoint servers.

Customer Data Service
The newest service, introduced in February 2004 with the release of MapPoint Web Service version 3.5, is the customer data service. This lets you upload blocks of geographic and demographic data to the Microsoft server, either manually or automatically using an extract-transform-load function on a regular schedule. This allows your applications to leverage your own data?such as office locations, customer sites, or shipping centers?the same way you’d work with MapPoint’s own databases. More about this service can be found here.

Building on the Object Model
Obviously, a listing of API methods isn’t enough to help you build a Web or client/server application that leverages the MapPoint Web Service. That’s where the SDK comes in, with hundreds of pages of documentation on the object model, entity types and properties, data sources, and sample code in both C# and Visual Basic .NET.


Share the Post: