For the second project, we want you to apply all that you’ve learned this quarter 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 or science.

This project is all about using pre-existing API Functions (just like we had a library of existing function for project 1 and the Wordle assignment) to interact with real-time service data from Yelp and Spotify/Last.FM. Though you won’t have to get into the weeds of exactly how APIs work, you’ll need to understand the different functions as your disposal (think of them as building blocks) and how you can connect them together to produce a working program!

Your tasks are as follows

  1. Pick one of two themes: food (Yelp) or music (Last.FM and Spotify)
  2. Get oriented with the relevant helper modules apis.gui, apis.yelp, apis.audio, apis.twilio, which will help you interact with the service providers.
  3. Fulfill the requirements of the assignment (described below)
  4. Earn up to 5 points extra credit by completing optional enhancements
  5. Other logistics:
    • You are welcome to collaborate in groups of 2-3 or work individually.
    • If you wish to work in a group, follow the directions in the below button BY TUESDAY AT 11:59PM CST. No exceptions will be made.
Signing-up for a Team Step 1. Both you and your team member(s) must sign-up using this form by Tuesday at 11:59pm.

If all team members do not sign-up using this form, none of you will be eligible to submit the assignment as a team.

Step 2. On Wednesday, prior to class, you will be added to a Canvas Group (e.g. "Project 2 Team ..."). Until you are added to a Canvas partner group, do not submit anything to the Canvas assignment If you ignore this rule, you will receive a 0 on the project.

Step 3. Once you're added to your Canvas group, you should be able to submit both like a normal assignment with one change: only one of you need submit the PY file to Canvas. It will automatically be "submitted" on behalf of your partner as well.

Modification to our Academic Honesty Policy for this Exercise Only - for registered Teams only. Working with a team will necessitate looking at the same code base. That is okay for this assignment for people who successfully register with a team. For everyone else, our AHP remains the same.

Note that working with a team does not mean you can simply split the work across members. I highly recommend you instead practice pair programming either while being physically co-located or via Zoom and screen-sharing. This will be by far the most effective and the most fun way to complete the assignment.
Warning: audio project is Experimental Spotify recently re-designed their API due to user misuse meaning much of their API is untested which could result in problems that are hard to diagnose. If you are unwilling to diagnose such problems, have a lot going on during finals week, or are otherwise unsure of your programming skills, you should NOT choose the audio option.
Possibility: Working with TV / Movies Prof. Bain is working on a version of this assignment for TVs and Movies. If you are more interested in doing this version of the project and are willing to be a little adventurous, come see Prof. Bain. Note: this would likely mean not being able to start on the project itself until the middle of Week 10.

Part 0 - Setup. Please Read Carefully

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

A. Download the starter files

The “Project Starter Files” button is at the very bottom of the page. PLEASE READ THROUGH THE WHOLE ASSIGNMENT ONCE BEFORE DOWNLOADING THE FILES.

pip is a program that allows us to install external libraries, made by people around the world, for use in our own program. Normally, pip is a command-line tool where you interact with it using the Terminal (on a Mac) or Command Prompt (on a PC). In fact, we’ll see it in action during the pre-recorded lecture next week!

In order to complete P2, you’ll need to install three external Python packages and upgrade an existing one. You can choose one of the following methods:

Installing Using our Installer [Recommended] Inside the starter files, open the install_python_packages.py file in IDLE and then run it. You'll be presented with 6 options, each with a number associated with them.
  1. To install sendgrid (which is made by a company called Twilio), requests, and customtkinter, you'll first enter option 0, then when the program asks which package you want to install, you'll enter the name of the package you want to install. It'll install it and then go back to the menu.
  2. Pick 0 again and install the second and third modules.
  3. Finally, you'll enter option 1 to upgrade certifi. DO NOT HALT THE EXECUTION OF THIS PROGRAM.
  4. Instead, to exit, select option 5 at the menu.
If you run into any issues on this part, you'll need to post on edSTEM or come to OH. If the program prints out any errors (it won't necessarily be in red text so make sure to read what it outputs), feel free to copy and paste it into your post so we can diagnose the issue.
Want to try installing via pip? [Optional - Advanced] If you'd like to try to use the command prompt, visit this page.

B. Get the API access token

Download the secret_tokens.py file from the Canvas files tab (or by clicking here after logging into Canvas) and move it inside of the apis folder (included in the project starter code).

Having trouble downloading the secret_tokens.py file?
  • First go to our Canvas page.
  • Click on the Files tab.
  • Hover your mouse over secret_tokens.py and then hit the "3 dots menu" that appears.
  • Select "Download"
A few people have reported on their computers this downloads as an HTML file rather than a PY file. If that happens to you, follow these steps in stead:
  • First go to our Canvas page.
  • Click on the Files tab.
  • Click on secret_tokens.py.
  • On the resulting screen that pops-up, click the Download button near the top.

C. Run the verification script

Inside the tests folder, open the run_verification.py file in IDLE and run it. If you get a message that looks like this (after entering your email address) then you’re good to go (note: you may see different DEBUG statements than the below - that’s okay as long as you don’t get any errors).

test_tokens (tests.test_authentication.TestAuthentication.test_tokens) ... ok
test_get_backup (tests.test_authentication.TestAuthentication.test_get_backup) ... ok
test_can_import_customtkinter (tests.test_gui.TestGUI.test_can_import_customtkinter) ... ok
test__issue_get_request_only_one (tests.test_audio.TestAudio.test__issue_get_request_only_one) ... 
DEBUG - _issue_get_request:
Here's the request we're going to make.
 https://api.spotify.com/v1/search?q=beyonce&type=track 
You can't access it in a browser, but you can double check the inputs you gave the function are part of the URL.
DEBUG - _generate_authentication_header:
 Auth token expired, time to refresh!
DEBUG - _generate_authentication_header:
 Generating new Spotify Authentication Token...
Loading: https://api.spotify.com/v1/search?q=beyonce&type=track
ok
test_execute_business_queries_just_one_simplified (tests.test_yelp.TestYelp.test_execute_business_queries_just_one_simplified) ... 
DEBUG: Here's the request we're going to make.
 https://api.yelp.com/v3/businesses/search?location=Tallahassee, FL&limit=10 
You can't access it in a browser, but you can double check the inputs you gave the function are part of the URL.
ok
test_can_import_twilio (tests.test_twilio.TestTwilio.test_can_import_twilio) ... ok
test_can_import_twilio_api_module (tests.test_twilio.TestTwilio.test_can_import_twilio_api_module) ... ok
test_can_send_email (tests.test_twilio.TestTwilio.test_can_send_email) ... Please enter your email address: i.am.very.cool@hotmail.com
ok

----------------------------------------------------------------------
Ran 8 tests in 44.503s

OK
Did you get an SSL: CERTIFICATE_VERIFY_FAILED error? This is the most common error and often effects Macs when you run the above (or when trying to send an email), and has to do with a technology that helps you securely connect to web pages called SSL. To fix this, please open your finder and navigate to your Applications > Python 3.12 folder (or whichever python version you have installed). Then, double-click on the Install Certificates.command file. Your email functions should now work! Re-run the verification file.


If you run into some other error, double check you followed the setup instructions, triple check you installed and upgraded the various Python packages, and then come to OH or post on edSTEM with the specific error you’re having.

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 I pay real money for and manage. Please only use these keys for the course assignments. If you have other app ideas for Last.FM, Spotify, Yelp, Twilio, etc., just register for your own keys and use those; I’ll even help you get started. They are all free for low-volume transactions. If you misuse the keys for our course, you risk disabling the ability to do these queries for everyone in the class.

Part 1 - Using a GUI

Just like in last week’s Wordle assignment, we’ll be working not with the Python Interpreter window but instead with a Graphical User Interface (GUI - pronounced goo-ee) to interact with our programs. We’ve done our best to abstract most of the detail of designing and using GUIs out of the assignment so that you can get your app up and running quickly. Regardless of which of the below options you choose, there’s a few things you need to know about how the GUI is setup.

Both of the project templates contain a Main Menu button, a Quit button, and several buttons that correspond to the base features for that project. Essentially, each button represent a function in your program that is run when that button is pressed. If you look towards the bottom of each template, you’ll find a dictionary called actions whose keys are button names and whose values are function names. If you want to add additional features to your program, simply define a new function like normal (though it can’t have any inputs) and then add it to the actions dictionary with a logical name as its key and the new function’s name as its value.

There’s really only four functions in this library you’ll need to know about.

GUI Docs

Part 2 - Choose Your Adventure

Option 1: Yelp

Yelp Project Details

Option 2: Music

Music Project Details

What to Turn In

  1. The .py file you worked in (i.e. restaurant_finder.py or mixtape_maker.py)
  2. You will only submit 1 file per team on Canvas so it's imperative you're registered for the right team on Canvas.
  3. Upload an MP4/MKV/MOV (NOT a link but an actual file) that demos your system to the VIDEO assignment on Canvas.
  4. Please add notes about which extra credit options you choose to pursue this at the top of your Python file in a series of 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.

Template Files

These are available at the bottom of each Project track page.