CS A131 Fall 2017 Final Project:
Final Project: Driving Directions
**This project is adapted from Alex Thornton
Your program will describe a trip taken between a sequence of locations, the goal being to travel from the first location to the second, then from the second location to the third, and so on, until reaching the last location. Based on the user’s input, it will show different information about the trip, such as turn-by-turn directions, distances and times, etc.
1 Mapquest and Open Data APIs
For our work on this project, we’ll need both the Open Directions Service and the Open Elevation Service. Both of these are web-based APIs. The Open MapQuest API uses HTTP, with queries described using a URL, and with responses returned in JSON (JavaScript Object Notation)format.
The two APIs you’ll need are described in detail at the links below. You certainly won’t need to read all of the documentation, but you’ll want to take a look around and familiarize yourself with what the API can do, because part of your goal in this project is to decide what parts of the API you’ll need to solve your problem.
• MapQuest Open Directions Service documentation
• MapQuest Open Elevation Service documentation
1.1 Creating an account and getting an API Key
MapQuest’s API requires an API Key, which links your usage of the API to an account and authorizes you to use the API. Before you can make use of the API, you’ll need to obtain your own API Key. Do not share your API Key with other students! You’ll only need to do this once, and you’ll be able to use your API Key for all of your work on this project once it’s been created. Obtaining the API Key is free for non-commercial use.
1.2 Visit the MapQuest Developer site in your browser.
1. Part of the way down the page, you’ll see a button that says Get Your Free API Key. Click that button. (Note if the button isn’t there, wait a little while and it’ll be back.)
2. A form will be displayed, in which you can choose a username, a password, and so on. Fill in the necessary information, and be sure to use an email address that you have access to; you’ll need to receive emails from MapQuest along the way.
CS A131 Fall 2017 Final Project: 100pts Due: Mon 12/11/2017 11:59PM
3. Once you’ve created your account, you’ll be logged in and presented with some choices, click on Manage Keys.
4. Click on Create a New Key to get an API Key that allows you to use the Open MapQuest APIs.
5. When asked, supply an App Name (csa131 pymap).
Now that your key has been created within your MapQuest Developer profile, you will be able to obtain your API key. Click the name of your application, which you should now see on the page, which will reveal more information about it. Make a note of both the Consumer Key and Consumer Secret somewhere; you’ll need these later. Notice that there is a limit on the number of times you can use the API each month–currently 15,000 transactions per month–and that you can see in this same area of the MapQuest Developer web site how many of these transactions you’ve used at any given time. The limit should be plenty for our use, but you may nonetheless want to keep an eye on it. After you’ve completed this process, your MapQuest API Key will have been created, though it should be noted that it might take a little bit of time for it to become active, so don’t panic if you’re not able to use it right away.
1.3 Testing your API Key
Wait a little while after creating your API Key, then it’s time to test that it’s working. Open your favorite web browser; enter a URL in the following format into the browser’s address bar and press Enter, replacing APIKEY with the Consumer Key part of the API key that you created in the previous step.
http :// open.mapquestapi.com/directions/v2/route?key=APIKEY&from=Irvine %2CCA\&to=Los+Angeles
%2CCA
If successful, you should receive a result that looks roughly like this (though you’ll get a lot more output than this):
{“route”:{“hasTollRoad”:false ,”computedWaypoints”:[],”fuelUsed”:1.93,”hasUnpaved”:false ,”
hasHighway”:true ,”realTime”:-1,”boundingBox”:{“ul”:{“lng”: -118.244476 ,”lat”:34.057094} ,”
lr”:{“lng”: -117.794593 ,”lat”:33.6847}} ,”distance”:40.675 ,”time”:2518,”locationSequence”
:[0,1],”hasSeasonalClosure”:false ,”sessionId”:”545ca8d0 -03c3 -001e-02b7 -7cb8 -00163 edfa317
“,”locations”:[{“latLng”:{“lng”: -117.825982 ,”lat”:33.685697} ,”adminArea4″:”Orange County
“,”adminArea5Type”:”City”,”adminArea4Type”:”County”,”adminArea5″:”Irvine”,”street”:””,”
adminArea1″:”US”,”adminArea3″:”CA”,”type”:”s”,”displayLatLng”:{“lng”: -117.825981 ,”lat”
:33.685695} ,”linkId”:44589954 ,”postalCode”:””,”sideOfStreet”:”N”,”dragPoint”:false ,”
adminArea1Type”:”Country”,”geocodeQuality”:”CITY”,”geocodeQualityCode”:”A5XCX”,”
adminArea3Type”:”State”},
…
This format is JSON (JavaScript Object Notation), which is a common format of information returned from web APIs like this one. Unfortunately, it’s not presented in a way that’s particularly readable for us–though, in general, that’s not a problem for our program, because our program doesn’t have the same aesthetic needs that we do. To take your first look at what’s being returned, you might find it useful to copy all of the text
2
CS A131 Fall 2017 Final Project: 100pts Due: Mon 12/11/2017 11:59PM
returned to you, then visit jsonprettyprint.com and paste the text and ask for it to be “pretty-printed”. You’ll now see the same text, but spaced in a way that will make its structure more obvious to a human reader.
Once it’s “pretty-printed,” take a look through MapQuest’s response–don’t worry if you don’t understand every detail, but start to get a rough sense of what kind of information is available and how it’s organized. When you want to know the details, the API documentation will explain everything you need, and you’ll find that you can discover a lot of the details through additional experimentation. But it’s important that you allow yourself to build an understanding gradually; this is not something you’ll necessarily be able to figure out right away, but a lot of the information won’t turn out to be relevant in this project, anyway. One characteristic that distinguishes real-world work from the often-sanitized kinds of projects you do in courses like this is the need to find small nuggets of information you need amongst large amounts of documentation that is largely irrelevant to the problem you want to solve.
2 The input
Your program will take input in the following format. It should not prompt the user in any way; it should simply read whatever input is typed into the console, and you should assume that your user knows the precise input format.
• An integer whose value is at least 2, alone on a line, that specifies how many locations the trip will consist of.
• If there are n locations, the next n lines of input will each describe one location. Each location can be a city such as Costa Mesa, CA, an address such as 2701 Fairview Rd, Costa Mesa, CA, or anything that the Open MapQuest API will accept as a location. (The details of what is acceptable as a location is described here).
• A positive integer (i.e., whose value is at least 1), alone on a line, that specifies how many outputs will need to be generated.
• If there are m outputs, the next m lines of input will each describe one output. Each output can be one of the following:
– STEPS for step-by-step directions, meaning a brief description of each maneuver (e.g., a turn, entering or exiting a freeway, etc.) you would have to make to drive from one location to another
– TOTALDISTANCE for the total distance traveled if completing the entire trip
– TOTALTIME for the total estimated time to complete the entire trip
– LATLONG for the latitude and longitude of each of the locations specified in the input
– ELEVATION for the elevation, in feet, of each of the locations specified in the input
3
