CS110: Fall 2021

Intro to Computer Programming with Python

CS110: Fall 2021

Assignments > P2: Make a Recommendation App

Due on Wed, 12/08 @ 11:59PM. 40 Points.

Project Starter Files

Project Overview

For the second project, we want you to apply what you’ve learned to build a program that searches, filters, and displays data. Because much of what programmers do involves manipulating and making sense of data for many different purposes, this will likely be a skill that many of you will leverage in the future if you do any kind of data analytics. Moreover, even beyond computer programming, having a more in-depth understanding of how these systems are designed and how they interconnect with one another is relevant to all of us.

Your tasks are as follows:

  1. Pick one of two themes: music (Spotify) or food (Yelp)
  2. Get oriented with the relevant helper modules apis.yelp, apis.spotify, apis.twilio, which will help you interact with the service providers (Yelp, Spotify, and Twilio)
  3. Fulfill the requirements of the assignment (described below)
  4. Earn up to 8 points extra credit by completing optional enhancements
  5. Other logistics:
    • You are welcome to collaborate in groups of 2 or 3.
    • Please complete the setup before the Thanksgiving holiday (see below).
    • Please start on this assignment early: like with anything, you’ll get out of it what you put into it.

Setup: Please Read Carefully

You will need to install some dependencies and edit some files before you begin this project:

A. Install the Python dependencies

Open your Terminal (MacOS) or Command Prompt (Windows) and execute the following commands (from any directory):

pip3 install sendgrid                        # a module to interact with Twilio
pip3 install requests                        # a module for querying internet resources
pip3 install --upgrade certifi               # for SSL certificates

B. Download the starter files

Click the “Project Starter Files” button above.

C. Get the API access token

Download the my_token.py file from Canvas and save it inside of the apis folder (included in the project starter code).

D. Run the verification script

Inside the tests folder, run the run_verification.py file (either in Idle or in your preferred python IDE).

If you get a message that looks like this…

test_token (test_authentication.TestAuthentication) ... ok
test_get_key (test_authentication.TestAuthentication) ... ok
test__issue_get_request_only_one (test_spotify.TestSpotify) ... 
ok
test_execute_business_queries_just_one_simplified (test_yelp.TestYelp) ... 
ok
test_can_import_sendgrid (test_sendgrid.TestSendgrid) ... ok
test_can_import_sendgrid_api_module (test_sendgrid.TestSendgrid) ... ok

----------------------------------------------------------------------
Ran 6 tests in 5.935s (time may vary)

OK

…then you’re ready to begin the project. Otherwise, talk to your TA and they can help you troubleshoot.

Note: If you have a Mac and encounter a security (SSL) error, please open your finder and navigate to your Applications > python3.x folder (or whichever python version you have installed). Then, double-click on the Install Certificates.command file.

IMPORTANT

You will be using a number of web data services to complete this assignment, which require the use of API keys (kind of like passwords) that Sarah pays for and manages. Please only use these keys for the course assignments. If you have other app ideas for Twitter, Spotify, Yelp, SendGrid, etc., just register for our own keys and use those. They are all free for low-volume transactions.

Option 1: Yelp!

For option 1, you are going to use the Yelp API to create a restaurant recommendation system. I have created a yelp module for you, located in the apis folder to help you. All of the apis/yelp.py functions have been documented here. Here is a demo video of how your program should work:

Note: this is only one way of implementing this program, and includes some extra credit features. Feel free to do it your way!

Please implement the following (5) required features of your restaurant recommendation system:

1. Allow the user to select among the Yelp restaurant categories

You will give the user the option of selecting one or more restaurant categories that can be used to filter the restaurants. To do this you will do the following:

  1. Present the user with some subset from the list of available categories (see yelp.get_categories() for the complete list).
  2. Ask the user to select one or more categories and store their selections in a variable called categories (a comma-separated list of categories).
  3. Proved the user with a way to either clear out or update their selected categories.

2. Allow the user to set the sorting criteria

How results are ordered really matters in search. Yelp allows 4 different options for sorting results: best_match, rating, review_count, distance. Given this, the user should be able to select how they want their results to be filtered.

3. Allow user to view restaurants that match the selection criteria

Given the user’s selected location, categories, and sorting criteria:

  1. Retrieve the restaurants, and allow the user to specify an additional keyword before executing the search (see demo).
  2. Print the retrieved restaurants to the screen in some coherent format (feel free to use the display functions that have already been made for you in the corresponding modules).

4. Allow the user to preview an individual restaurant

Given the matched restaurants:

  1. Allow the user to preview an individual restaurant
  2. This should include (a) more detail about the restaurant, and (b) some reviews of the restaurant.
  3. Use the yelp.get_businesses() and yelp.get_reviews() helper functions to help you.

5. Allow the user to email a restaurant recommendation

After the user has previewed a restaurant, ask them if they want to email the restaurant recommendation so someone. If so, email them a link to the restaurant and some details about it. Use the twilio.send_mail function to help you.

Extra Credit Options (Up to 8 Points)

[2 Points] Allow the user to select a location

You will give the user the option of selecting a location to search (which defaults to Evanston, IL). The user should be able to update this location whenever they want. Once it is set, this location will be used to filter their restaurants (Yelp requires a location).

[3 Points] Allow the user to set the price filters

You will give the user the option of selecting one or more price filters. The way the filters work: 1=$, 2=$$, 3=$$$, and 4=$$$$. So, if I only wanted to see $ and $$, my price filter would be: price_filter=1,2. Given this, the user should be able to select one or more price filters, and clear out their price filters if they want.

[2 Points] Allow the user to filter by restaurants that are “open now”

Enhance your program by also giving the user the option of specifying only restaurants which are currently open.

[3 Points] Allow the user to filter by restaurants that are “hot and new”

Enhance your program by also giving the user the option of specifying only restaurants which are “hot and new.” See the Yelp documentation for more info

[3 Points] Extra Credit: Generate an HTML file

Generate an HTML file with the table of recommended restaurants as well as some information about each one. Consider embedding images of the restaurants into the file.

[5 Points] Extra Credit: Create a Map of Restaurants

Given the HTML file you’ve just generated, figure out how to create a map of all of the restaurant recommendations (using folium).

[5 Points] Incorporate another information source

In addition to searching Yelp, try integrate data from Twitter (or some other source) using some of the lecture samples from Week 9. You can earn up to 5 points for each provider that you incorporate.

[5 Points] Figure out how to attach the HTML file to an email

Take a look at this article.

Rubric (40 Possible Points)

Feature Points Scoring Guidelines
Main Program Loop 5 points
  • Loop handles errors (incorrect inputs)
  • Loop prompts the user for their input
  • Loop honors user requests
  • Loop does not exit unless user asks to quit
Category selection 8 points
  • Displays the user's selected categories(s) if any
  • Displays the available Yelp categories from which to choose
  • Allows user to select among categories
  • Allows user to clear out selected categories and start over
Ordering/Sorting Criteria 4 points
  • Allows user to specify their preferred ordering criteria (best_match, rating, review_count, distance).
Previewing matching restaurants 8 points
  • Results honor user’s selected location, categories, and sorting criteria
  • Allows the user to specify a search keyword
  • Prints restaurants to the screen in some coherent format.
Previewing individual restaurant 8 points
  • Allows user to preview an individual restaurant
  • Includes detail about restaurant
  • Includes restaurant reviews
Sends email 3 points
  • Successfully emails a restaurant recommendation and reviews to a user
Code Quality 3 points
  • All functions, variables, and file_names have pneumonic names / are snake case (up to -2 points)
  • Code is organized and without unused or redundant code. Please remove commented out code that isn’t running (to help our graders) (up to -3 points)
Video 1 point
  • Your video clearly demonstrates the features you implemented.
Extra credit Up to 8 points
  • Students completed various EC options according to the specifications above.

Option 2: Spotity

For option 2, you are going to use the Spotify API to create a music recommendation system. I have created a spotify module for you, located in the apis folder to help you. All of the apis/spotify.py functions have been documented here. Here is a demo video of how your program should work:

Note: this is only one way of implementing this program, and includes some extra credit features. Feel free to do it your way!

Please implement the following (3) required features of your restaurant recommendation system:

1. Allow the user to select one or more genres of music

You will give the user the option of selecting one or more genres that can be used to “seed” the Spotify song recommendations system. To do this you will do the following:

  1. Present the user with a list of available genres using the spotify.get_genres_abridged() function — feel free to modify it.
  2. Ask the user to select one or more genres and store their genre selections in a list variable called “genres”

2. Allow the user to select one or more artists

You will also give the user the option of selecting one or more artists that can also be used to “seed” the Spotify song recommendations system. To do this you will do the following:

  1. Provide a way for the user to search for and display artists (use the spotify.get_artists() function)
  2. Provide a way for the user to select the artists they’re interested in and store the corresponding artist objects in a list variable called “artists”
  3. Allow the user to either clear out or append artists to their artists list.

3. Generate and email song recommendations

Given the user’s selected genres and artists:

  1. Retrieve the recommended tracks using the spotify.get_similar_tracks() function.
  2. Print the retrieved tracks to the screen in some coherent format (feel free to use the display functions that have already been made for you in the corresponding modules).
  3. Ask the user if they want to email the tracks to someone, and if so, send an email of the list of track recommendations. Use the spotify.get_formatted_tracklist_table_html() function to help you build a nice tracklist (see the video) that can be emailed.

NOTE: The spotify.get_similar_tracks() function’s job is to get recommendations based on seed data. As documented in the docstring, the get_similar_tracks() function requires at least one of the following arguments:

  • artist_ids (list): A list of artist ids
  • track_ids (list): A list of track ids [extra credit see below]
  • genres (genres): A list of genres

Spotify only allows 5 seed values (in any combination). In other words: len(artist_ids) + len(track_ids) + len(genres) must be between 1 and 5.

Extra Credit Options (Up to 8 Points)

[3 Points] Allow the user to select one or more tracks

If you have time and need extra credit, you may enhance your program by also giving the user the option of selecting one or more tracks to “seed” the Spotify song recommendations system. To do this, you will do the following:

  1. Provide a way for the user to search for and display tracks
  2. Provide a way for the user to select the tracks they’re interested in and store the corresponding track objects in a list variable called “tracks”
  3. Allow the user to either clear out or append tracks to their tracks list.

[3 Points] Extra Credit: Generate an HTML file

Generate an HTML file with the table of recommended tracks as well as some information about the artists (and tracks) that went into seeding the playlist. Consider embedding images of artists, albums, and/or audio players into the file.

[2 Points] Extra Credit: Search for similar artists

Allow the user to discover artists who are similar to a given artist.

[2 Points] Extra Credit: Search for playlists by keyword

Allow the user to find playlists based on a keyword search.

[5 Points] Incorporate another information source

In addition to searching Spotify, try integrate data from YouTube or Twitter as well using some of the lecture samples from Week 9. You can earn up to 5 points for each provider that you incorporate. In other words: 5 points for YouTube, 5 points for Twitter, etc.

[5 Points] Figure out how to attach the HTML file to an email

Take a look at this article: https://stackoverflow.com/questions/40656019/python-sendgrid-send-email-with-pdf-attachment-file

Rubric (40 Possible Points)

Feature Points Scoring Guidelines
Main Program Loop 5 points
  • Loop handles errors (incorrect inputs)
  • Loop prompts the user for their input
  • Loop honors user requests
  • Loop does not exist unless user asks to quit
Genre Selection 8 points
  • Displays the user's selected genre(s) if any
  • Displays available genres
  • Allows user to select among genres presented
  • Allows user to clear out their selected genres and start over
Artist Selection 12 points
  • Allows user to search for artist
  • Allows user to select among artists returned from Spotify
  • Allows user to clear out selected artists and start over
  • Displays the names of the user's selected artists
Generate and email recommendations 11 points
  • Correctly passes arguments of correct type into the get_similar_tracks() function.
  • Displays recommendations to screen (including track name and artist name).
  • Successfully emails the recommendation list.
Code Quality 3 points
  • All functions, variables, and file_names have pneumonic names / are snake case (up to -2 points)
  • Code is organized and without unused or redundant code. Please remove commented out code that isn’t running (to help our graders) (up to -3 points)
Video 1 point
  • Your video clearly demonstrates the features you implemented.
Extra credit Up to 8 points
  • Students completed various EC options according to the specifications above.

What to Turn In

  1. Your code as a zip file. This should include all of the files that make your code work.
  2. Please only submit 1 set of code files per team and list who you collaborated with in the submission comments (so that when we run our code similarity checker, we don’t flag you and your collaborators). Your teammates should then just post a comment that says, “see X’s submission for the code. My collaborators were X and Y.”
  3. A link to your video. Make sure that it’s publicly viewable – not just to @u.northwestern.edu b/c faculty don’t have access to that domain, unfortunately).
  4. Any notes about your project and/or any extra credit options you pursued (if applicable). You can do this as a separate text file inside of your zip file or in the submission comments. If you did the extra credit, PLEASE DO NOT FORGET TO TELL USE WHAT YOU IMPLEMENTED — We want to give you credit for the effort that you put into your program.