Fetching grades data

[michael5]

Hello developers,

For a statistics project for our school I'm currently interested in discovering how many of our students actually complete their courses. A course is considered completed if the student has been awarded more than 80% of the available points in the course, so in order to evaluate how many students complete their courses I need to calculate how many students, per course, who have been awarded more than 80% of the available points.

This has turned out to be a lot more complicated than I initially assumed it would be. I've tried a few approaches:

1. The submissions object: https://canvas.instructure.com/doc/api/submissions.html
   Manually mapping student data from here was easy enough, but the operation is quite intense because I have to repeat the process on a lot of courses so I'd rather avoid doing that.
2. The grades report (Account > Reports > Grades) is perfect and exactly what I need but I can't seem to find a way to fetch the actual data within these reports with the API. If I could get the CSV file that is generated by these reports either as a CSV file, JSON data or even raw text, that would be sufficient.
   
   
3. I haven't experimented too much with this but it may be possible to pull the numbers from the New Analytics if that comes with an API, however at a glance it only seems to offer an average grade and not a total of points awarded in the course.

Since the number(s) that I'm trying to fetch are already in the system, I feel like I'm missing something and that this should be an easy request to make with the API. Did I overlook something? Any suggestions would be very much appreciated. 🙂

Thanks in advance,

Michael

[DecoyLex · Accepted solution]

The enrollments API is probably what you're looking for. It includes each enrollment as well as a student's current grade and final grade as calculated by Canvas. Here's what I get by doing a GET request to /api/v1/courses/123/enrollments:

[
    {
        "id": ...,
        "user_id": ...,
        "course_id": ...,
        "type": "StudentEnrollment",
        "created_at": ...,
        "updated_at": ...,
        "associated_user_id": null,
        "start_at": null,
        "end_at": null,
        "course_section_id": ...,
        "root_account_id": 1,
        "limit_privileges_to_course_section": false,
        "enrollment_state": "active",
        "role": "StudentEnrollment",
        "role_id": 3,
        "last_activity_at": ...,
        "last_attended_at": null,
        "total_activity_time": ...,
        "sis_import_id": ...,
        "grades": {
            "html_url": ...,
            "current_grade": "B+",
            "current_score": 88.6,
            "final_grade": "B+",
            "final_score": 88.6,
            "unposted_current_score": 88.6,
            "unposted_current_grade": "B+",
            "unposted_final_score": 88.6,
            "unposted_final_grade": "B+"
        },
        "sis_account_id": ...,
        "sis_course_id": ...,
        "course_integration_id": null,
        "sis_section_id": ...,
        "section_integration_id": null,
        "sis_user_id": ...,
        "html_url": ...,
        "user": {
            "id": ...,
            "name": ...,
            "created_at": ...,
            "sortable_name": ...,
            "short_name": ...,
            "sis_user_id": ...,
            "integration_id": ...,
            "sis_import_id": ...,
            "login_id": ...
        }
    }
]

You can also add ?include[]=current_points to the end to get the raw points value of the student's enrollment.

You'd probably want to use the unposted_current_score for your report since it's the percentage that the instructor sees in the gradebook and would be the most likely value they'd use when entering grades into SIS manually (if that's relevant to you).

Enrollments API: https://canvas.instructure.com/doc/api/enrollments.html#method.enrollments_api.index

[michael5]

Ah, that's it. It seems I've been working with it before but I completely forgot there was grades data in this object - thanks a lot! 🙂

[James]

@michael5 

A quick question.

Regarding item 2 -- using the Grades Report -- if the Grades Report has what you need, then why use the API at all? You said that if you could get the CSV generated by the report, it would be sufficient. I'm assuming that you have admin rights since you are familiar with the report. Without admin rights, you would only be able to get the data for your students.

You can request a report through the API. Through the web interface, it emails a message when the report is done, which isn't suitable for API, but might be okay in a one-off. However, you should be able to save your report ID and then check the status periodically to wait until it's finished. Then use the file_url to download the report. Note that the file_url is probably not an API call, so you don't want to include the authorization header on it.

Still, if this is something that you just need once, or even once a semester, it seems that going the easy route would save a lot of headache and time.

The enrollments report that @DecoyLex mentioned would need to be called for each course and then you would have to compile the results together into something usable.

[michael5]

True, but the whole hurdle is it has to happen automatically ie. programmatically since I'm building an application that will update on its own. A lot of the statistical data on display in the application can already be accessed by administrators and instructors, but in order for them to get the actual numbers and information that they need, they often have to request reports from various sources and combine datasets in spreadsheets on their own. So I'm mainly building for convenience and for automation of administrative tasks. If I have to manually feed the application with data it defeats the point. But yeah, if it was one-off, I'd just use the grades report like you say.