Getting Started With MapQuest OpenAPI

Get to know OpenAPI basics by implementing MapQuest’s samples on your own website

The MapQuest OpenAPI is, like Google’s and Yahoo’s before it, an script interface that allows you to leverage the not inconsiderable power of a heavyweight geo-information provider to produce one’s own maps for display on one’s own webpages, tailoring content and mashing up what the user thinks is interesting and fun with base information from a trusted source.

The OpenAPI, of course, has something of a learning curve for the new user (we are learning our way around it right now). The good news is that you don’t have to invest a great deal of time of learning to get an idea of how it works. As a matter of fact, MapQuest provides a folder of samples that you can mount in your very own web space with just a little bit of trouble.

Get Registered

MapQuest OpenAPI (OAPI) is free, but requires registration. The OpenAPI home page is here; go there and find the OpenAPI registration link in the text (there are at least two).

1. OAPI registration requires a minimum of information: A first name, last name, email address, “Referer” URL, and username. The “Referer” here means the place on the web where you’re going to house your OAPI scripts.
2. If you’ve not done so already, go to whatever webspace you’ll use and define the place where you’ll be placeing the OAPI scripts. For this test run, I used my homepage of http://www.rdrop.com/users/eagle, and opened a folder on that server called “MQ”. My Referer link, thus, is http://www.rdrop.com/users/eagle/MQ.
3. Clicking “next” at the end of this form will take you to a standard-looking EULA acceptance page. Read and electronically sign it, and click “next” again. This starts the sequence that will, within 2 business days (according to MapQuest; mine happened sooner than that) result in your receiving two emails from openAPI@mapquest.com; one is the terms and conditions, and the other contains essential information on logging into the OAPI Technical Resource Center and a OAPI access key, based on the URL of the Referer you supplied.

Once you get those emails, save them. They have essential information on accessing and using the OAPI resources.

Logon To The Resources

Next step in this process is to get online with the MapQuest Technical Resource Center (TRC),http://trc.mapquest.com. Use your username and password that you were sent to gain admittance.

The TRC is a cleanly designed site, with the obvious intention to get you straight to the resource you want. The top three (“Getting Started”, “Documentation”, and “Examples”) are what we’ll concern ourselves with this time around. The selection range is:

• Getting Started: a short textual page with beginning tips. Here you’ll find a link to a PDF version of the OAPI Developers Reference Guide, a link to the Forums, and a link to the Examples.
• Documentation: a brief page with two links, one to the PDF version of the Reference Guide and one to an online HTML version.
• Examples: links to example script files.
• Forums: developer and user fora.
• My Account: Account settings, including the Referer URL you supplied earlier. This provides for easy changing of the Referer URL if you get it wrong or mistyped, or if it changes.
• Tools: other useful geocoding tools and links

Take a brief time to tour the site, and look over the documentation (the PDF is about 5.6MB, but the HTML, of course, loads instantly).

Getting The Goods and Getting Them Up

After you’ve gotten orientated to the documentation, it’s time to get the goods. From the TRC home page, click Examples. You go to a page with a brief text, a single link, and a short list of instructions. We’ll expand on MapQuests instructions by desicrbing what we did to follow them.

1. Download the Examples Archive: click on the “Map and Routing Samples” link and the download of a PC-ZIP archive, MQOpenAPI_samples.zip, will commence
2. Unzip the Archive: the archive will create a folder that contains not just the OAPI scripts but also supporting graphics and cascading style sheets.
3. Upload the Files to your Web Server: We used Dreamweaver MX 2004 for this, making sure that the links to graphics and to scripts were correct. We did a little editing here. They were uploaded to the folder/path http://www.rdrop.com/users/eagle/MQ/.
4. Modify all example html pages to use your OpenAPI key: This is the tricky part, but if you have your files loaded into the proper space, it’ll just bit a bit of cut and paste work. Near the top of all HTML files in the example set, find the following line:
<script src="http://web.openapi.mapquest.com/oapi/
transaction?request=script&key=YourKey"
type="text/javascript"></script>
   Replace the string YourKey with the access key string that MapQuest sent you in thier email.
5. After you’ve uploaded your scripts, point your browser to the index.html file at the Referer URL address you’ve already supplied.

If your links are solid, the following image should appear in your browser:

Success! All links sound: each of those links will take me to a demonstration file that puts OAPI through its paces (click to enlarge)

Success! I now have a complete menu of OAPI examples mounted on my website. You can go here to view it and to put the maps through thier paces. They run from the simple (a simple display of an area centering on Harrisburg-Lancaster PA) to multiple maps, CSS-supported skinning, and moderatly advanced geocoding.

Troubleshooting

Though conceptually simple there are many opportunities for mistyping or miscopying to introduce errors. Here are the common ones we ran into:

1. Broken links: if the page won’t load, the biggest culprit is a perennial one: the miscoded link. This is more or less likely depending on your web editing suite and your familiarity with it. load the index.html file into your web editor and make sure the links from the file match the acutal paths in the web space.
2. No Images Load on the Index page: Really the same problem as above. Correcting the code on the image links in the CSS section of the index.html page solved this problem.
3. The dreaded “Referer/Key combination” bug: This is an easy problem to run into. What the API is saying is that the access key in the javascript source URL doesn’t refer to the URL you’ve actually loaded the files into. Check to see if you’ve copied/pasted the access key correctly. If you’re absolutely sure that you’ve copied and pasted the access key correctly then go to the TRC site and go to the “My Account” tab, check the Referer URL and make sure it absolutely matches the web address you’ve loaded the example files into. If not, correct the URL and click “Update”, which should correct the problem (there’s no need to apply for a new access key).

That’s all there is to getting registered and getting online with the MapQuest OpenAPI. Go and play with it; remember that it’s still in Beta, so expect the bug or two, but report it and they will work to correct it.

Over the next few How-To’s Days we’ll look into making our own maps, and perhaps even attempt a mashup of our own. Stay Tuned!