Introduction to MapQuest® Advantage™ API

by Kevin Farnham
August 27, 2007

Introduction

The MapQuest® Advantage™ API is a rich mapping API that is used by hundreds of businesses, both large and small, to provide their customers with online mapping services. MapQuest has its roots in cartography from a time prior to the existence of the World Wide Web. This brings significant advantages to MapQuest that other geospatial platforms cannot provide: namely, MapQuest's enormous database of place-related information. When you search for a place using MapQuest, you are searching through multiple databases, through data that has been carefully gathered, scrutinized, and updated.

The MapQuest Advantage API offers a powerful selection of capabilities to developers. This article introduces MapQuest Advantage and outlines its core capabilities. There are currently three Advantage APIs: the original server-side API, which supports C++, Java, and .NET; the JavaScript API, which was MapQuest's first client-side API, used to build RIA applications including the ability to build drag and drop, pan map navigation, and layering of points, shapes and rollovers; and the AS3 API for ActionScript 3.0, released in June 2007. Core capabilities that are introduced in this article include map navigation, geocoding, search, points of interest, and routing.

Signing Up to Use MapQuest® Advantage

The MapQuest Advantage API home page is the starting point for using the API. This page includes links to introductory materials and a link to the Online Demo. The demo shows you what's possible using the API. If you're considering applying MapQuest Advantage™, this detailed and well-organized demo is surely worth a few minutes of your time.

On the main Advantage API page, there is also a link enabling you to request evaluation access to the API, so you can begin experimenting with it. To gain access, you have to provide basic information about yourself and your company, and also basic information about your testbed infrastructure:

• Operating system
• Web server
• Scripting/web language
  

Be sure to select "Advantage API" in the "Product You Wish to Evaluate" drop-down menu.When your evaluation request is approved, you'll receive a user name and a password, providing you access to the MapQuest Technical Resource Center.

MapQuest® Advantage Server-Side API

The MapQuest Advantage Server-Side API is designed to permit development of rich mapping capability using a wide variety of development platforms and protocols, including:

• Java: Supported on specific JDK releases for multiple OS platforms.
• .NET: Supported on Windows with C#, VB.NET, and ASP.NET.
• C++: Supported on Windows and Linux.
• XML: Available for implementing the MapQuest Server-Side API on non-supported platforms.
• HTTP: Available for implementing the MapQuest Server-Side API on non-supported platforms.

The server-side API is an object-oriented API. As such, the methods for applying the API in Java, .NET, or C++ are similar: the API object properties and methods are similarly accessed using each platform. Hence, if you learn how to use the API using C++, the learning curve to implement the API in Java or .NET is minimal. Here's the example provided in the .NET Developer Guide, showing the statements to set an address:

C++ Interface:

OriginAddress.SetStreet("123 Main");
   OriginAddress.SetCity("Pittsburgh");
   OriginAddress.SetState("PA");
   OriginAddress.SetPostalCode("15215");
 OriginAddress.SetCountry("US");

C# Interface:

OriginAddress.Street = "123 Main";
   OriginAddress.City = "Pittsburgh";
   OriginAddress.State = "PA";
   OriginAddress.PostalCode = "15215";
 OriginAddress.Country = "US";

Java Interface:

OriginAddress.setStreet("123 Main");
   OriginAddress.setCity("Pittsburgh");
   OriginAddress.setState("PA");
   OriginAddress.setPostalCode("15215");
 OriginAddress.setCountry("US");

As youcan see, the API is very consistent across different languages.

The MapQuest API documentation, available in the Technical Resource Center, is thorough. For example, the .NET Developer Guide (PDF) is 175 pages long, covering everything from client-server communication, security, and encryption to mapping features like geocoding, generating maps, displaying points of interest, and proximity searching. The Developer References are online HTML documents that cover the API classes in detail. The references are generated using Doxygen, a documentation system that works for many languages, including C++, Java, Python, PHP, and C#. Between the developer guides and the Doxygen-generated developer references, the developer is provided with a superb foundation for developing applications that utilize the MapQuest server-side API.

To make a map using the server-side API, you execute a series of steps that define a GIF image. The MapQuest server application will create the defined image and provide its URL. In this sense, the server-side MapQuest API can be considered a "dynamic" API: the map images that you'd like to present are dynamically generated based on the specifications provided to the server. Here are the steps for generating a map image and receiving its URL:

1. Create a Session object.
2. Create a MapState object, and set its size, scale, and center.
3. Add the MapState object to the session using the session's AddOne method.
4. Add any other desired parameter objects to the session.
5. Call the GetMapFromSessionURL method to get a URL for the dynamically produced image, or call the GetMapImageFromSession method to receive the actual image.

The server-side API provides all kinds of options for customizing your maps. The DTStyle object can be applied to modify map icons, colors, text label fonts, label background colors, and even visibility (i.e., you can temporarily hide or show specific map features). The MapQuest server-side API is a truly powerful and flexible API, which came into being as a result of decades of activity by cartographers who started out working on paper maps. If you need to generate fully customized maps, the MapQuest server API is likely the best mapping utility you'll find. It is powerful and robust, brings you detailed datasets, can be deployed on multiple platforms, and offers the flexibility to address almost any image-based mapping need your company might have.

MapQuest® Advantage™ JavaScript API

In addition to the full-featured server-side MapQuest API, MapQuest is also available for building rich web applications through the Advantage API JavaScript Toolkit. The JavaScript API (JS-API) interfaces with the MapQuest Toolkit, which provides tile-based mapping that will be familiar to anyone who uses mapping sites on the Web. To achieve a grab and pan map navigation, the tiled-based toolkit doesn't offer the full flexibility in terms of map generation options that the server-side map functions provide. Map tiles deployed by the toolkit are pre-rendered, static images, which are periodically regenerated with MapQuest data updates; hence, the maps that can be retrieved using thetoolkit utilize the tiles that currently exist for each geographic region. In other words, you can't arbitrarily define a custom map scale or select a different color palette like you can with the server-side API maps that are generated on demand.

The MapQuest Toolkit and JS-API have rapidly gained popularity, both because tiled mapping is so widely accepted by the user community, and because developing a site that deploys tiled maps using the JS-API and Mapping Toolkit is relatively simple. Using the MapQuest Toolkit, you can generate a web page that presents a MapQuest map using just three key HTML elements:

A <script> MapQuest Map Toolkit definition element in the <head> section.

A <div> in the <body> section to hold the map image.

A <script> execution element in the <body> section to retrieve the map using the MapQuest Toolkit's MQTileMap() object instantiator.

"Three lines of code and I can have real maps on my site?"

Well, yes, it really is that simple. Let's take a look at the steps in detail.

You start out by creating a simple HTML web page. In the <head> section, you define the MapQuest Map Toolkit JavaScript file that is to be included for access by your page. Like this:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
 <html>
 <head>
 <title>Quick Map</title>
 <script src="http://btilelog.access.mapquest.com/tilelog/transaction?transaction=script&
key=_YOUR_KEY_&ipr=true&itk=true&v=b2btk" type="text/javascript"></script>
 </head>

Notice the <script> statement. In the key= phrase, you'd insert the JavaScript key you received when you registered to use the MapQuest APIs. In the v= phrase, you can define which version of the JS-API you would like to use. The most recent version of the API is 5.1, so v=5.1 would pull-down that version.

Next you set up a <div> element to contain the map. This is pretty basic:

<body>
 <h2>My MapQuest Map</h2>
 <div id="mapWindow" style="width:900px; height:520px;"></div>

Finally, you execute the script method to retrieve the map image and insert it into your <div>

<script type="text/javascript">
   myMap = new MQTileMap(document.getElementById('mapWindow'));
 </script>
 </body>
 </html>

What does this code produce? Go to company.mapquest.com/aapi5/QS/1_quickmap.html to have a look. View the HTML source, and you'll see that indeed you can have mapping capability on your website using the MapQuest Toolkit and JavaScript API with just three lines of code.

But, of course, we want more! What else can we do with JavaScript? Here's where we get back into some of the core strengths of MapQuest. With the JS-API and the MapQuest Toolkit, you have full access to the same deep databases that are a core strength of the server-side API. Hence, a lot of mapping power is at your fingertips if you choose to apply the Toolkit and the JS-API on your site.

Navigation

The initial three-line application produces a map of the entire globe. Focusing in on a particular region of the globe, and viewing it at a more close-up scale, is easily accomplished using the JS-API. You simply modify your instantiation of the MQTileMap() object to include specification of a zoom level (1-16, with 1 being farthest out, 16 being maximum zoom) and a latitude and longitude position. You can also define whether you want a satellite view. For example, changing the call to:

<script type="text/javascript">
   myMap = new MQTileMap(document.getElementById('mapWindow'),9,new MQLatLng(40.0446,-76.4131),"sat");
 </script>

produces a satellite view of the region near Mountville, Pennsylvania.

Geocoding

Geocoding is the action of determining the latitude and longitude position of a location that is specified using a street address. The capability of any mapping application to accurately geocode addresses depends on the depth and accuracy of the underlying database. As I've stated, the underlying databases are one of the primary advantages MapQuest offers developers, when compared with other online mapping APIs.

Geocoding is too complex a topic for complete coverage in this article; a subsequent article will describe MapQuest's geocoding capabilities in detail. To geocode using the JavaScript API, JavaScript objects are applied to access the MapQuest server methods for geocoding. It's a bit complicated, but if you want to experiment with geocoding using the JS-API, the description in the AAPI AJAX Developer's Guide will show you how to do it.
SearchThe JS-API also provides an interface to the MapQuest spatial search server. You can define the following region shapes to localize your search:

• A radius around a center point
• A rectangular box
• A distance from anywhere along a specified route
• An irregular polygon (defined by a set of latitude/longitude points)

Points of Interest

The MQPoi() object lets you add a point of interest to your map. Each point of interest can have a title and information content that is displayed on the map, with options for making the information visible, invisible, visible when the mouse hovers over the location, etc.

Routing

Computing and displaying routes is a core functionality that almost every site that has mapping capability will need. You need to be able to tell your potential customers (or whomever) how to get to your location. MapQuest's routing functions produce both a text description of driving instructions and capability to plot the route on a map. Routing is a big topic, which I'll be covering in detail in a later article in this series.

Conclusion

MapQuest offers developers a fully featured, powerful API, backed by deep databases constructed by cartographers over the past 30+ years. No other mapping API offers this. With MapQuest, you have the choice of accessing a server-side API that offers robust mapping customization; a JavaScript API offering interfaces with a MapQuest Toolkit to provide convenient integration of mapping capabilities on websites using modern JavaScript/AJAX programming techniques; and the new AS3 API, for accessing MapQuest capabilities using ActionScript 3.0.

References

• The MapQuest Advantage API Home Page: The starting point for using MapQuest Advantage
• Online demo: A detailed online demonstration of the most significant MapQuest Advantage API features
• The MapQuest Advantage evaluation request page
• The MapQuest Technical Resource Center