MapQuest Developer Network Blog

There's nothing that makes you so aware of the improvisation of human existence as a song unfinished. Or an old address book. - Carson McCullers

In Part 1 I showed you how to get started with the MapQuest Advantage API by getting a developer key. In Part 2 I put that key to use by providing access to a basic map in the Map It! widget. Part 3 showed you how to incorporate basic geocoding. In Part 4 I discussed more advanced geocoding topics - including handling multiple matches and specifying geocode search options. Part 5 discussed adding widget options including the default zoom level, specifying point of interest icons, and the default map type. Part 6 discussed how to add direction capabilities to the widget. In this final installment I'll talk about how easy it is to integrate address searching with the Mac OS X Address Book application.

Address Book Searching

The Mac OS X Address Book application is bundled with the OS X operating system, providing a way for users to organize their contacts and associated information including their addresses. Also included with Mac OS X is an Address Book widget, which provides access to the Address Book database from a widget. I've explored the Address Book widget code, and extracted the AddressBookPlugIn. Plug-ins are native code that can be used to access operating system levels features from a widget's JavaScript interface.

Stand in the place where you live, Now face North, Think about direction, Wonder why you haven't before - REM

In Part 1 I showed you how to get started with the MapQuest Advantage API by getting a developer key. In Part 2 I put that key to use by providing access to a basic map in the Map It! widget. Part 3 showed you how to incorporate basic geocoding. In Part 4 I discussed more advanced geocoding topics - including handling multiple matches and specifying geocode search options. Part 5 discussed adding widget options including the default zoom level, specifying point of interest icons, and the default map type. In this installment I'll discuss how to add direction capabilities to the widget!

Directions

Listing 1 demonstrates how to add directions to our widget map. I've added an additional search box where the user can enter the destination address. I've use the Java application developed in Part 3 to obtain the coordinates of the route beginning and destination points. Using the coordinates, I've created the MQGeoAddress object for both points. A new session is created for routing. The starting point and destination are added to the way points. Once the route is calculated through the doRoute method, the highlighted route is added to then added to the map.

It is not down in any map; true places never are. - Herman Melville

In Part 1 I showed you how to get started with the MapQuest Platform by getting a developer key. In Part 2, I put that key to use by providing access to a basic map in the Map It! widget. Part 3 showed you how to incorporate basic geocoding. In Part 4 I discussed more advanced geocoding topics - including handling multiple matches and specifying geocode search options. In this installment I'll discuss adding some options to the widget. Specifically I'll discuss setting the default zoom level when adding an API, specifying point of interest icons, and the default map type.

Younger hackers are hard to classify. They're probably just as diverse as the old hackers are. We're all over the map. - Larry Wall

In Part 1 I showed you how to get started with the MapQuest Platform by getting a developer key. In Part 2 I put that key to use by providing access to a basic map in the Map It! widget. Part 3 showed you how to incorporate basic geocoding. In this installment I'll discuss more advanced geocoding topics - including handling multiple matches and specifying geocode search options.

Multiple Matches

The version of the Map It! widget developed in Part 3 added the ability to plot a point of interest on the map. In the Java application that was developed to return the coordinates of an address, only the first match is returned. What if the user enters a street address without the house number? Geocoding would actually return multiple results. We need to change the getLocation method developed in Part 3 to return each match. On a search without a house number for example, the geocoding process would return points for each range of addresses. Listing 1 shows how the getLocation method has been modified:

Somewhere there is a map of how it can be done. - Ben Stein

In Part 1 I showed you how to get started with the MapQuest Advantage API by getting a developer key. In Part 2 I put that key to use by providing access to a basic map in the Map It! widget. In this installment I'll show you how to incorporate basic geocoding.

About Geocoding

Geocoding is the process of converting an address into latitude and longitude coordinates that uniquely identify a location, and you can use to plot on a map. Applications using the MapQuest Platform can calculate the latitude and longitude of:

• Street addresses and intersections, the highest accuracy geocoding methods.
• Street blocks, including the nearest block to an invalid house number.
• Postal codes, including ZIP, ZIP+2, and ZIP+4 codes.
• City centers.
• US state and Canadian province centers.
• Country centers.
• Centers of other administrative areas that are used internationally.

The Map It! application will allow users to enter an address in one of the following forms:

• street address, zip
• street address, city, state
• street address, city, state, zip
• street address, city, state, zip, country

That is the exploration that awaits you! Not mapping stars and studying nebula, but charting the unknown possibilities of existence. - Leonard Nimoy

In Part 1, I provided an overview of the MapQuest Platform, and provided instructions on how to obtain your own developer key. The developer key is required to integrate MapQuest into your application through the JavaScript API.

About Map It!

In Part 2 and 3 of building the Map It! Application, I will be creating the Mac OS X Dashboard widget shown in Figure 1.

Figure 1

Users enter an address in the search box at the top of the widget, and that point is automatically plotted and zoomed in on the map below. Users can switch between map, satellite, and hybrid views. They can also use the controls on the left to navigate and move around the map.

I've discussed building Mac OS X Dashboard widgets previously on my AOL Developer Network blog, here and here. For the Map It! Dashboard widget - I used Apple's Dashcode to jumpstart my development. Even though I used Dashcode - the techniques to integrate the MapQuest Platform, I'll review here can be utilized however you develop Dashboard Widgets.

It's important to understand that Dashboard Widgets are mini Web 2.0 applications - with their programmatic interface coming from JavaScript - so the JavaScript API is almost (I explain why it's almost in Part 3) perfect fit! All of the techniques I review in building Map It! can be used by Web 2.0 developers as well!

Adding the MapQuest JavaScript Library

In the main widget HTML page you'll need to include the following SCRIPT tag to import the JavaScript library:

<script src="http://btilelog.access.mapquest.com/tilelog/transaction?transaction=script&key=**YOUR-KEY**ipr=true&itk=true&v=5.2.0" type="text/javascript"></script>

You need to replace **YOUR-KEY** with the key that was provided in the email when you signed up for the MapQuest Platform, as discussed in Part 1.

Creating the User Interface

To place the map on the widget - you'll need to create a DIV to hold the map. In the Map It! application I created the following DIV tag.

<div id="myMap" style="width: 550px; height: 300px;"></div>

Now that you have a place to display the map, the next step is to get the map displayed in the DIV. This is simply done by create a new MQTileMap object and associating with the DIV, as shown here:

// Create a MQTileMap object and display it in the myMap DIV
myMap = new MQTileMap(document.getElementById('myMap'));

The final step is to add the Large Zoom and view controls. These controls allow the user to zoom in and out of the map, and select the type of map that is displayed (road, satellite, or hybrid). This is accomplished with the following code:

// create a new Large Zoom Control
var myLZControl = new MQLargeZoomControl(myMap);

// add it to the map at the specified offset from the Top Left corner
 myMap.addControl(myLZControl, new MQMapCornerPlacement(MQMapCorner.TOP_LEFT, new MQSize(1,1)));

// create a new View Control
var myVControl = new MQViewControl(myMap);

// add it to the map at the specified offset from the Top Right corner
myMap.addControl(myVControl, new MQMapCornerPlacement(MQMapCorner.TOP_RIGHT, new MQSize(20,20))); 

That's all that you need to add a map!

Referrers

While Dashboard widgets function just like typical Web 2.0 applications, they have two shortcomings that need to be overcome when working with the MapQuest Platform. First, when including the JavaScript library, your key maps back to the information provided when you signed up for developer access. Since Dashboard widgets run locally from your desktop they will not have a referrer. As shown in Figure 2, you'll need to add the referrer * and enable blank referrers. It's important to understand the risks of enabling blank referrers so read the Warning not carefully. Since we're not running the Dashboard widget from a web server - as all widgets are accessed locally - blank referrers are required. I'll discuss the second shortcoming with Geocoding and Mac OS X Dashboard widgets in the Part 3.

Figure 2

Conclusion

In Part 3 I'll show you how to add Geocoding to the widget to plot a point of interest based on the address entered in the search box. For your reference, here are some references to the MapQuest Platform:

• MapQuest Developer Network - http://developer.mapquest.com
• MapQuest JavaScript API Developer Guide - http://developer.mapquest.com/content/documentation/JavaScript/QuickStart/DevGuide-AdvantageAPI-Javascript.pdf
• MapQuest JavaScript API Reference - http://developer.mapquest.com/content/documentation/JavaScript/DevRef/index.html
• MapQuest JavaScript TileMap Reference - http://developer.mapquest.com/content/documentation/JavaScript/TileMap/index.html
• MapQuest Technical Resource Center - http://trc.mapquest.com

A civilized nation can have no enemies, and one cannot draw a line across a map, a line that doesn't even exist in nature and say that the ugly enemy lives on the one side, and good friends live on the other. - Thor Heyerdahl

The MapQuest Platform has become the preferred way for developers to integrate rich cartography into their applications. Using the MapQuest Platform, developers can provide street and satellite views. In addition points of interest, navigation, geocoding (converting an address to map coordinates), and routing are all supported. In this series of blogs - I will show developers how to build a Mac OS X Dashboard widget that will eventually provide mapping, point-to-point directions, and integration with the built-in Address book application - all powered by the MapQuest Platform.

Development Platforms

The MapQuest Platform APIs are accessible from a wide variety of development platforms and protocols. From the server side this includes: Java, .NET, and C++. From the client side this includes: AS3 (Adobe ActionScript 3), FUJAX, and JavaScript.

Signing Up

The MapQuest Developer Network is the place to get started. The site provides an overview of the APIs features, in addition to links providing an online demo, product brochures and more. Before a developer can begin using the APIs in their applications they need to sign up for a Free Edition or Developer license. As shown in Figure 1, you can start that process at - http://developer.mapquest.com/Home/WhyJoin - click on the Register button in the upper right.

Figure 1

You'll need to provide basic personal information, and accept the terms and conditions.

Shortly after you submit your information, you'll receive an email, you'll need to click on the link in the email to confirm your request. Once confirmed, you'll receive a second email in about 20 minutes. This email will contain the URL to the MapQuest Technical Resource Center, your username (which is the email address you used to sign up) and a temporary password, which you will change after your first login. Also included in the message is the authentication information you'll need to access the MapQuest Platform from your application. I'll be using this information later in this series of blogs.

After you login to the Technical Resource Center and change your password, as shown in Figure 2, you'll have complete access to the documentation, SDK downloads, examples, and your account information. Click on the My Account link to view the information shown in Figure 3.

Figure 2

Figure 3

In addition to your support form user id, you will be able to configure the referrers for your account. The referrer information basically provides information about the domains where you will be accessing the MapQuest Platform. Note at the bottom that there is an option to permit blank referrers. Read the warning note closely if you enable this option. I will discuss the specific referrer issues that occur with a Mac OS X Dashboard widget in the next post in these series.

Conclusion

You now know how to get started with the MapQuest APIs. Here are some resources for you to review before I begin to build the Dashboard widget. Dig in!

• MapQuest Technical Resource Center
• MapQuest Developer Network
• MapQuest API Documentation
• MapQuest Code Samples
• MapQuest Online Demo