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.
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).
- 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.
- 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.
- 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.
- 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
- Unzip the Archive: the archive will create a folder that contains not just the OAPI scripts but also supporting graphics and cascading style sheets.
- 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/.
- 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:
Replace the string
YourKeywith the access key string that MapQuest sent you in thier email.
- After you’ve uploaded your scripts, point your browser to the
index.htmlfile at the Referer URL address you’ve already supplied.
If your links are solid, the following image should appear in your browser:
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.
Though conceptually simple there are many opportunities for mistyping or miscopying to introduce errors. Here are the common ones we ran into:
- 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.htmlfile into your web editor and make sure the links from the file match the acutal paths in the web space.
- 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.htmlpage solved this problem.
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!