How to use mapquest api

CS A131 Fall 2017 Final Project: 100pts Due: Mon 12/11/2017 11:59PM

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.

1

http://open.mapquestapi.com/directions/
http://open.mapquestapi.com/elevation/
https://developer.mapquest.com/
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

http://open.mapquestapi.com/common/locations.html
CS A131 Fall 2017 Final Project: 100pts Due: Mon 12/11/2017 11:59PM

You can feel free to assume that the input will match the format described above.

3 The output (when a route was found by MapQuest)

After reading the input and processing it–downloading information from the MapQuest API, etc.–your program will generate the specified outputs in the forms described below. Each output must be preceded by a blank line, to set each one off from the others. The outputs must be written in the order that they were specified in the input (e.g., if the input said TOTALDISTANCE, then LATLONG, then TOTALTIME, the outputs must be shown in that order).

• The STEPS output should begin with the word DIRECTIONS alone on a line, followed by one line of output for each maneuver that needs to be made along the path from the first location to the last.

• The TOTALDISTANCE output should be the words TOTAL DISTANCE, followed by a colon and a space, followed by the total distance (in an integer number of miles, rounded to the nearest mile) for the entire trip.

• The TOTALTIME output should be the words TOTAL TIME, followed by a colon and a space, followed by the total time (in an integer number of minutes, rounded to the nearest minute) that would be required to take the entire trip.

• The LATLONG output should be the word LATLONGS alone on a line, followed bby a latitude and longitude, one of each per line, for each of the locations specified in the input, in the order specified in the input. The latitude should come first, followed by a space, followed by the longitude.

– The latitude’s format is a number of degrees (formatted to two decimal places) followed by either N for north or S for south.

– The longitude’s format is a number of degrees (formatted to two decimal places) followed by either W for west or E for east.

• The ELEVATION output should be the word ELEVATIONS alone on a line, followed by an integer number of feet of elevation, one per line, for each of the locations specified in the input, in the order specified in the input. If MapQuest reports the elevation with a decimal part, round to the nearest integer.

After the last output, print a blank line, and then the following copyright statement, alone on a line:

Directions Courtesy of MapQuest; Map Data Copyright OpenStreetMap

Contributors.

4

CS A131 Fall 2017 Final Project: 100pts Due: Mon 12/11/2017 11:59PM

3.1 The output (when no route was found)

When no route was found by MapQuest–e.g., if you look for driving directions from Costa Mesa, CA to Lisbon, Portugal, you won’t find any–the program should simply output a blank line, followed by NO ROUTE FOUND alone on a line. This also includes the scenario where one or more of the locations was not valid (e.g., you looked for driving directions between locations that MapQuest did not recognize).

3.2 The output (when MapQuest returns an error)

When MapQuest returns another kind of error, other than a route not being found (e.g., the AppKey was invalid, you have no network connectivity, or MapQuest was down), the program should simply output a blank line, followed by MAPQUEST ERROR alone on a line.

4 An example of the program’s execution

The following is an example of the program’s execution, as it should be. Boldfaced, italicized text indicates input, while normal text indicates output. Note that the map data (the maneuvers, latitudes and longitudes, etc.) are hypothetical.

3

4533 Campus Dr, Irvine, CA

1111 Figueroa St, Los Angeles, CA

3799 S Las Vegas Blvd, Las Vegas, NV

5

LATLONG

STEPS

TOTALTIME

TOTALDISTANCE

ELEVATION

LATLONGS

33.68N 117.77W

34.02N 118.41W

36.11N 115.17W

DIRECTIONS

West on Campus Dr.

Right on Bristol

CA-73 North

Transition to I-405 North

Transition to I-110 North

Exit 9th Street

5

CS A131 Fall 2017 Final Project: 100pts Due: Mon 12/11/2017 11:59PM

South on S Figueroa St.

Left on W 18th St.

Enter I-10 East from W 18th St.

Transition to I-15 North

Exit S Las Vegas Blvd.

TOTAL TIME: 317 minutes

TOTAL DISTANCE: 365 miles

ELEVATIONS

542

211

2001

Directions Courtesy of MapQuest; Map Data Copyright OpenStreetMap

Contributors

5 Implementation Tips

As with the previous project, you’ll be required to write your program using multiple Python modules (i.e., multiple .py files), each encapsulating a different major part of the program. The following modules would be a good way to break this problem down into component parts:

• final p maps.py: A module that interacts with the Open MapQuest APIs. This is where you should do things like building URLs, making HTTP requests, and parsing JSON responses.

• final p out.py: A module that implements the various outputs. Each kind of output that can be generated by the program must be implemented as a separate class; see below.

• final p main.py: A module that reads the input and constructs the objects that will generate the program’s output. You will execute this module in your script file.

5.1 Output generators as classes

Each of the different kinds of outputs that your program can generate is required to be implemented as a Python class, which contains attributes that configure it and a method that generates the output given the response from the Open MapQuest APIs.

All of these classes must have a method with the same signature (i.e., the same name, the same parameters, and the same type of return value) that is used to generate one kind of

6

CS A131 Fall 2017 Final Project: 100pts Due: Mon 12/11/2017 11:59PM

output, so that your main module can create a list of output generators of various types, then generate all of its output by simply looping through them and asking each to generate its output.

5.2 Divide and Conquer

Start in increments that make sense. One problem you know you’ll need to solve is reading the input. As a starting point you may read the input and print something back to the console that demonstrates that you read it correctly. You can test this from the Python interpreter before proceeding.

After that, choose another slice of functionality. For example, you might write a function that builds the URLs that you’ll use to call into one of the Open MapQuest APIs. Call that function from the Python interpreter, then take its output and try to use a web browser to open the URL; if you get back a JSON response, that tells you that you’re on the right track.

Given the URL to information on the web that your program will need, you just want to download and use that information. In order to do that we will be using the Python module urllib.request or requests and the methods available.

6 To submit

Create a typescript output (using the command script) called final p.scr

Create a tar file called final p.tar containing the following files:

1. final p main.py

2. final p maps.py

3. final p out.py

4. final p.scr

5. final p.txt

To create the tar file, use the following command:

tar cf final_p.tar final_p_main.py final_p_maps.py final_p_out.py final_p.scr final_p.txt

Submit the file final p.tar to canvas by Monday, December 11, 11:59pm

7

Mapquest and Open Data APIs
Creating an account and getting an API Key
Visit the MapQuest Developer site in your browser.
Testing your API Key
The input
The output (when a route was found by MapQuest)
The output (when no route was found)
The output (when MapQuest returns an error)
An example of the program's execution
Implementation Tips
Output generators as classes
Divide and Conquer