Example usage of the planetterp api

planetterp_api.md

This is an example of using the planetterp api in python.

Let's walk through an example python program which will print the number of students who received an A in a given course.

First, we'll get a course from the user:

course_name = input("Enter a course: ")

Now we'll get that course's grade data from the api using the grades endpoint. Since we're retrieving grades for a course, we'll use the course parameter (instead of professor).

We'll make our request using the Requests library:

import requests

course_name = input("Enter a course: ")
grade_data = requests.get(f"https://api.planetterp.com/v1/grades?course={course_name}").json()

Now we can print the number of students who received an A, for each semester and section of this course (since the /grades endpoint returns all semesters and sections by default, not just the current one):

import requests

course_name = input("Enter a course: ")
grade_data = requests.get(f"https://api.planetterp.com/v1/grades?course={course_name}").json()

for section_data in grade_data:
    num_a = int(section_data["A"])
    course = section_data["course"]
    section = section_data["section"]
    semester = section_data["semester"]
    print(f"{num_a} students received an A in {course}, section {section}, semester {semester}")

This works (go ahead and run it for yourself! Try entering "CMSC131" when prompted for a course name), but what if the user enters an invalid course name? This program will crash. We will walk through how to explicitly handle this error case.

If a course that doesn't exist is requested, the api will return the following response: {"error": "course not found"}. We will check for this error response as follows:

if 'error' in grade_data and grade_data["error"] == "course not found":
    raise ValueError(f"course {course_name} not found")

And that's it! Here's the entire program:

import requests

course_name = input("Enter a course: ")
grade_data = requests.get(f"https://api.planetterp.com/v1/grades?course={course_name}").json()

if "error" in grade_data and grade_data["error"] == "course not found":
    raise ValueError(f"course {course_name} not found")

for section_data in grade_data:
    num_a = int(section_data["A"])
    course = section_data["course"]
    section = section_data["section"]
    semester = section_data["semester"]
    print(f"{num_a} students received an A in {course}, section {section}, semester {semester}")

Thanks for taking the time to put this together.