Description

The purpose of this lab is to demonstrate your knowledge of using a third party API to retrieve data, and process the data in a JSON format to extract the information that you need. You will also demonstrate your knowledge of putting together a simple GUI to display results.

Introduction to the Problem

Open API (Application Programming Interface) allows programmers/developers to access proprietary software applications and web services. This allows programmers to access backend data from other organizations. Some popular open API's include Twitter, Facebook, Google, and LinkedIn. Anytime you are able to log into a website using your credentials for another site such as Facebook, LinkedIn, or Twitter, that site is using an open API. 

While open API's mean they are free to use, there are often restrictions to their use, like approval of a developer's account with Twitter. MapQuest is a company that provides online services related to maps.  For our project, we will use the MapQuest OpenAPI, not because it's necessarily better than, say, Google Maps, but because it is easier to get started with access to interesting information.  

Requirements

You will write a class, MapQuest, that will have a constructor and four methods: totalDistance, totalTime, directions, and pointOfInterest. 

• The constructor will take in one parameter, which is the API key. You must set up any other instance variables that are you used in the class in your constructor. 
• def totalDistance(locations: list)->float: this method will take in a list of locations. The locations can be a list of any number (including 0) of valid MapQuest locations. You do not need to validate any locations. Consider a list of 3 locations, then totalDistance will return the distance from locations[0] to locations[1] to locations[2], in that order.  If the list is empty or if there is only one location, then you should return 0. 
• def totalTime(locations:list)->int: this method will take in a list of locations and return the time it would take to travel to each point, starting from the first location and ending with the last location in the list. You do not need to validate any locations.  If the list is empty or if there is only one location, then you should return 0.  NOTE: Please use the 'time' field, which gives the time in integers. 
• def directions(locations:list)->str: this method will take in a list of locations and return a string that represents the "turn by turn" directions (can be taken from the 'narrative') starting from the first location and ending with the last location in the list. You do not need to validate any locations. If the list is empty or if there is only one location, then you should return an empty string.
  • Example: 
    locations = ['4533 Campus Dr, Irvine, CA', '1111 Figueroa St, Los Angeles, CA', '3799 S Las Vegas Blvd, Las Vegas, NV']
    directions(locations)
  • Will return:
    'Start out going northwest on Campus Dr toward Carlson Ave.\n
    Turn right onto Jamboree Rd.\n
    Merge onto I-405/San Diego Fwy.\n
    Merge onto I-110/Harbor Fwy via EXIT 37A.\n
    Take the Adams Boulevard exit, EXIT 20C.\n
    Turn left onto W Adams Blvd.\n
    Turn right onto ramp.\n
    Merge onto Figueroa St.\n
    FIGUEROA STREET.\n
    Start out going northeast on Figueroa St toward 9th St.\n
    Turn left onto 8th St.\n
    Merge onto CA-110/Pasadena Fwy.\n
    Take the US-101/I-5 exit, EXIT 24A.\n
    Merge onto US-101/Santa Ana Fwy.\n
    Stay straight to go onto San Bernardino Fwy.\n
    Merge onto I-15 E via EXIT 58A toward Barstow/Las Vegas (Crossing into Nevada).\n
    Merge onto NV-159 via EXIT 41A toward Charleston Blvd East.\n
    Turn left onto S Las Vegas Blvd.\n
    S Las Vegas Blvd becomes Las Vegas Blvd N.\n
    SOUTH LAS VEGAS BOULEVARD.\n'
• def pointOfInterest(locations: str, keyword: str, results:int)->list: this method will take in a string that represents a valid location (once again, you do not need to validate locations), a string that represents the keyword of what you are searching for (ex: hotel, restaurant, airport, coffee), and the results is the max number of results you want to return.
  • To ensure we have standardized results, please sort your results by distance. 
  • If the results is greater than the number found, then all points of interest will be added to the dictionarylist regardless of the value of results.  You will add the appropriate matching results to thedictionary, using the name of the establishment as the key, and the location/address(single string) as the value list. Each element should be a search result's "displayString". 

In addition to your MapQuest class, you will also create a GUI that will display the results of your pointOfInterest method. Your GUI should have

• custome title, and appropriate sized window (to fit the contents of the program, without being too big)
• two text fields, one for the location, and another for the keyword of what you are searching for.
• There should be a drop down field that has a list of numbers that will represent the max number (you must have at least 3 options, you can consider something like 5, 10, 25, etc.).
• You must display the results in a grid with the name of the establishment and the location.

Getting Started

For our project you will be using three API's provided by MapQuest, Open Directions API (Links to an external site.) , MapQuest Place Search API (Links to an external site.), and MapQuest Geocoding API (Links to an external site.)

You should refer to the documentation and be familiar with it, although knowing everything in the documentation is unnecessary for this assignment. 

Creating an account and getting an API Key

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 uses like ours.

• Visit the MapQuest Developer (Links to an external site.) site in your browser.
• Part of the way down the page, you'll see a button that says Get Your Free API Key. Click that button. 
• 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.
• Once you've created your account, you'll be logged in and presented with some choices, one of which is Manage Keys. Click that.
• You'll then see a button that says Create a New Key. Click that, because you're going to be needing an API Key that allows you to use the Open MapQuest APIs.
• When asked, supply an App Name (maybe ICS 32 Lab 4 would be a good choice). The Callback URL is not important for us, since we're not building a web application, so you can specify any URL.
• 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, too, 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.

Testing Your 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-00163edfa317",
"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"},

Submission

You will submit TWO files in a zip folder. 1) MapQuest class in a python script with the naming convention Lab4_YOURID.py. Ex: Lab4_12345678.py and 2) Your GUI implementation as a python script with the naming convention Lab4_YOURID_ GUI.py. Ex: Lab4_12345678_GUI.py. Do NOT send anything else. You will need to zip your script files by selecting both when you compress (this is necessary because when bulk downloading from Canvas, it will automatically change the file name, and your zip file is a layer that will protect your script file's name from changing). 

It is important that you name your file and all of your functions as outlined in this assignment to ensure that your file runs through automation. Failure to name your functions correctly will result in no points awarded for that function. Failure to name your file correctly will result in a 2 point penalty. 

Incorrect file submissions (this includes blanks files or "old versions") or files that contain syntax errors will be considered late and awarded no credit (please see syllabus for late policy). 

Please double check the file that you have submitted to Canvas to ensure that you have submitted the correct file in the correct format! If you find that you have submitted an incorrect file, you may resubmit your assignment as long as it is before the deadline. Your zip file will have a 2 after it, but this is irrelevant, as your Python file is still protected in the zip folder. 

Grading

totalDistance(3 points)
totalTime(3 points)
directions (5 points)
pointOfInterest(6 points)
GUI Implementation (3 points)

To ensure that you have named your functions correctly, please be sure to run the test file. The test file will only test for the MapQuest class, NOT the GUI. Please note that passing all the unit tests does NOT ensure full credit for this assignment. The test file checks for basic functionality, and does not cover all possible scenarios.

The functions will be tested for correctness, and if your function works for the test cases in our automation, then you will receive a certain number of points for each successful scenario. Keep in mind that it is up to you to thoroughly test your functions, and it should give the appropriate output for ALL scenarios that are covered in the preconditions. 

We will do our best to give partial credit for files that contain syntax errors or contains infinite loops, but this is not guaranteed, and you may receive no credit. It is your responsibility to ensure you are sending a script that does not contain any syntax errors or has logical errors that would cause an infinite loop. It is better to just leave out any functions you were unable to implement rather than send a half written function with syntax errors.