Assignments > P2: Make a Recommendation App

Due on Tue, 06/09 @ 11:59PM. 40 Points.

Project Starter Files

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 — from science to investigative journalism, to civic decision-making (and advocacy) — 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.

Please start on this assignment early: like with anything, you’ll get out of it what you put into it. You are also welcome to collaborate in groups of 2 or 3. If you do so, you must still submit your own copy of your code, 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).

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 pandas                          # a module for working with data
pip3 install ipython                         # also a module for working with data
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

Modify the apis/authentication.py file (located inside of the apis folder) and add the course API key. To do this:

1. Navigate to Canvas > Assignments > Project 2
2. Replace lines 8-16 of apis/authentication.py with the following line…
   API_TUTOR_TOKEN = '???'
   …but replace the ??? with the actual token.

D. Run the verification script

On your terminal / command line, navigate to your project02 directory. Then navigate into the tests directory (withing project02) and type:

python3 run_verification.py

If you get a message that looks like this…

test_token (test_authentication.TestAuthentication) ... ok
test_get_key (test_authentication.TestAuthentication) ... ok
test_malformed_query_yields_errors (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 7 tests in 5.935s

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.8 folder (or whichever python version you have installed). Then, double-click on the Install Certificates.command file.

Get Started

1. Pick one of two themes: music (Spotify) or food (Yelp)
2. Get oriented with the relevant helper modules apis.yelp, apis.spotify, apis.sendgrid, which will help you interact with the service providers (Yelp, Spotify, and Twilio)
3. Fulfill the requirements of the assignment
4. Earn up to 10 points extra credit by completing optional enhancements

IMPORTANT You will be using a number of web data services to complete this assignment. As such, you will be using API keys (kind of like passwords) that I pay for and manage. Please only use these keys for the course assignments. While it is certainly possible to use my sendgrid key to create a spam bot that will get me banned from Sendgrid forever, please don’t. I am trusting you. 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. 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 (consider using a pandas dataframe for this).

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 sendgrid.send_mail function to help you.

Extra Credit Options (Up to 10 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”

If you have time and need extra credit, you may enhance your program by also giving the user the option of specifying only restaurants which are currently open

[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)

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. 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 (consider using a pandas dataframe for this).
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 10 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.

[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)

What to Turn In

1. Your code as a zip file. This should include all of the files that make your code work.
2. An explanation of the features you implemented for the graders (and whether or not you attempted any extra credit. You can do this as a separate text file inside of your zip file or in the submission comments. 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.