Accessing grades information
:: services/grades module

These methods allow you to access information about user's grades.

Note that some methods in other modules may refer to grades (e.g. services/courses/user).

Methods

course_edition (deprecated) Get grade of user on given course_edition
course_edition2 Get grade of user on given course_edition
exam Get user's grades of given exam.
grade Get grade of given user and exam session.
grade_type Get info about grade type.
grade_type_index Get info about all grade types.
grade_types Get info about multiple grade types.
latest Get user's latest grades
terms (deprecated) Get grades of a user on given terms
terms2 Get grades of a user on given terms
update_grade BETA Update user's grade. (administrative)

services/grades/course_edition

Consumer: required Token: required Scopes: grades SSL: not required
https://usosapps.us.edu.pl/services/grades/course_edition

This method is deprecated, please avoid using it - read more

Suggested replacement: services/grades/course_edition2

Get grade of user on given course_edition
course_id required ID of course
term_id required ID of academic term
fields optional

Default value: value_symbol|passes|value_description|exam_id|exam_session_number

Selector of result fields you are interested in. The selector must contain subset of primary fields, which are described in the returns section of grade method.

format optional

Default value: json

Format in which to return values. See supported output formats.
callback optional

Required only if you've chosen jsonp as a return format.
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • course_grades - Array of dictionaries describing grades related to course edition's main exam. Dictionaries will have structure as defined in exam method, or null if course edition is not related with any exam report;

  • course_units_grades - Dictionary mapping course unit ID that are related to exam report to dictionaries describing exam grades as defined in exam method.

services/grades/course_edition2

Consumer: required Token: required Scopes: grades SSL: not required
https://usosapps.us.edu.pl/services/grades/course_edition2

Get grade of user on given course_edition
course_id required ID of course
term_id required ID of academic term
fields optional

Default value: value_symbol|passes|value_description|exam_id|exam_session_number

Selector of result fields you are interested in. The selector must contain subset of primary fields, which are described in the returns section of grade method.

format optional

Default value: json

Format in which to return values. See supported output formats.
callback optional

Required only if you've chosen jsonp as a return format.
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • course_grades - Array of dictionaries describing grades related to course edition's main exam reports. Dictionaries will have structure as defined in exam method.;

  • course_units_grades - Dictionary mapping course unit ID that are related to exam report to array of dictionaries describing exam grades as defined in exam method.

services/grades/exam

Consumer: required Token: required Scopes: grades SSL: not required
https://usosapps.us.edu.pl/services/grades/exam

Get user's grades of given exam.
exam_id required ID of an exam
user_id optional

Default value: (access token issuer)

User whose grades will be returned.
fields optional

Default value: value_symbol|passes|value_description|exam_id|exam_session_number

Selector of result fields you are interested in. The selector must contain subset of primary fields, which are described in the returns section of grade method.

format optional

Default value: json

Format in which to return values. See supported output formats.
callback optional

Required only if you've chosen jsonp as a return format.
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

Dictionary mapping exam session number to object returned by grade method for each session related to given exam or null if referenced grade does not exist.

Thrown errors:

  • object_forbidden - access to object denied.

    Possible reasons:

    • grade_forbidden - access token issuer does not have access to grade;

    • grade_write_forbidden - Access token issuer is not permitted to update grades. Permission rules:

      • course coordinator may update all grades;
      • lecturer may update grates in course unit exam report for participants of lectured groups.
      You need to use another methods to check if user has permissions.

  • object_not_found - some of the referenced objects do not exist; param_name is equal to exam_id.

services/grades/grade

Consumer: required Token: required Scopes: grades SSL: not required
https://usosapps.us.edu.pl/services/grades/grade

Get grade of given user and exam session. Note that only student that owns grade or authorized lecturer has access.

exam_id required ID of an exam
exam_session_number required number of exam session
user_id optional

Default value: (access token issuer)

User whose grades will be returned.
fields optional

Default value: value_symbol|passes|value_description|exam_id|exam_session_number

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section.

format optional

Default value: json

Format in which to return values. See supported output formats.
callback optional

Required only if you've chosen jsonp as a return format.
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • Primary:

    • value_symbol - symbolic representation of the grade;

    • passes - True if grade passes exam report;

    • value_description - text representation of the grade (LangDict object);

    • exam_id - ID of an exam report;

    • exam_session_number - given session number;

    • counts_into_average - boolean, true if this grade counts into average;

    • comment - comment visible for student and examinees;

    • private_comment - comment visible only for examinees. Access to private comment is allowed only with administrative consumer key;

      Additional permissions note: Consumer key with administrative access is required.

    • grade_type_id - ID of grade type (e.g. "ECTS" for ECTS grading system);

    • date_modified - time of last grade change as datetime string;

    • date_acquisition - time of grade acquisition as datetime string or null if not set;

    • modification_author - ID of user who edited grade as the last.

  • Secondary:

    • course_edition - Course edition related to grade.

      This field references objects returned by services/courses/course_edition method. See its returns section for possible subfields (only primary are allowed).

    • unit - If grade is related to course unit this field contains proper object.

      This field references objects returned by services/courses/unit method. See its returns section for possible subfields (only primary are allowed).

    • exam_report - Object describing exam report.

      This field references objects returned by services/examrep/exam method. See its returns section for possible subfields (only primary are allowed).

    • user - User whose grade is returned.

      This field references objects returned by services/users/user method. See its returns section for possible subfields.

Thrown errors:

  • object_forbidden - access to object denied.

    Possible reasons:

    • grade_forbidden - access token issuer does not have access to grade;

    • grade_write_forbidden - Access token issuer is not permitted to update grades. Permission rules:

      • course coordinator may update all grades;
      • lecturer may update grates in course unit exam report for participants of lectured groups.
      You need to use another methods to check if user has permissions.

  • object_not_found - some of the referenced objects do not exist.

    Possible reasons:

    • grade_not_found - referenced grade does not exist.

  • object_not_found - some of the referenced objects do not exist; param_name is equal to exam_id.

services/grades/grade_type

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapps.us.edu.pl/services/grades/grade_type

Get info about grade type.
grade_type_id required Identifier of the type.
fields optional

Default value: id|name|is_current

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section.

format optional

Default value: json

Format in which to return values. See supported output formats.
callback optional

Required only if you've chosen jsonp as a return format.
No additional OAuth arguments are required. If you provide any, they will be ignored.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • id - Identifier of the grade type;

  • name - a LangDict object with the grade type name;

  • is_current - True if grade type is current;

  • values - Array of dictionaries that describe grades.

    Dictionaries have following structure:
    • symbol - e.g. 5, ZAL
    • passes - boolean, true if student passes course with this grade.
    • decimal_value - numerical value of the grade.
    • name - a LangDict object with the grade name
    • order_key - int used for ordering grades (should not be displayed for users)

Thrown errors:

  • object_not_found - some of the referenced objects do not exist; param_name is equal to id.

services/grades/grade_type_index

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapps.us.edu.pl/services/grades/grade_type_index

Get info about all grade types.
fields optional

Default value: id|name|is_current

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section of grade_type method.

format optional

Default value: json

Format in which to return values. See supported output formats.
callback optional

Required only if you've chosen jsonp as a return format.
No additional OAuth arguments are required. If you provide any, they will be ignored.

Returned value:

A list of grade types, as defined in the grade_type method.

services/grades/grade_types

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapps.us.edu.pl/services/grades/grade_types

Get info about multiple grade types.
grade_type_ids required Pipe-separated list of grade type IDs.
fields optional

Default value: id|name|is_current

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section of grade_type method.

format optional

Default value: json

Format in which to return values. See supported output formats.
callback optional

Required only if you've chosen jsonp as a return format.
No additional OAuth arguments are required. If you provide any, they will be ignored.

Returned value:

A dictionary: your grade_type_ids will be mapped to dictionary's keys, and each value will contain the description of a grade type, as defined in the grade_type method or null if grade type is not found.

services/grades/latest

Consumer: required Token: required Scopes: grades SSL: not required
https://usosapps.us.edu.pl/services/grades/latest

Get user's latest grades
days optional

Default value: 7

Grades modified selected number of days ago will be returned
fields optional

Default value: value_symbol|passes|value_description|exam_id|exam_session_number

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section of grade method.

format optional

Default value: json

Format in which to return values. See supported output formats.
callback optional

Required only if you've chosen jsonp as a return format.
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

List of objects returned by grade method. Grades will be sorted descending by date of modification

services/grades/terms

Consumer: required Token: required Scopes: grades SSL: not required
https://usosapps.us.edu.pl/services/grades/terms

This method is deprecated, please avoid using it - read more

Suggested replacement: services/grades/terms2

Get grades of a user on given terms
term_ids required pipe-separated list of academic term ids
course_ids optional

Default value: (empty string)

pipe-separated list of course ids to limit results further
fields optional

Default value: value_symbol|passes|value_description|exam_id|exam_session_number

Selector of result fields you are interested in. The selector must contain subset of primary fields, which are described in the returns section of grade method.

format optional

Default value: json

Format in which to return values. See supported output formats.
callback optional

Required only if you've chosen jsonp as a return format.
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

Multilevel dictionary mapping term_id and course_id to object returned by exam. If term_id given in the term_ids param does not exist it will be mapped to Null.

services/grades/terms2

Consumer: required Token: required Scopes: grades SSL: not required
https://usosapps.us.edu.pl/services/grades/terms2

Get grades of a user on given terms
term_ids required pipe-separated list of academic term ids
course_ids optional

Default value: (empty string)

pipe-separated list of course ids to limit results further
fields optional

Default value: value_symbol|passes|value_description|exam_id|exam_session_number

Selector of result fields you are interested in. The selector must contain subset of primary fields, which are described in the returns section of grade method.

format optional

Default value: json

Format in which to return values. See supported output formats.
callback optional

Required only if you've chosen jsonp as a return format.
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

Multilevel dictionary mapping term_id and course_id to object returned by course_edition2. If term_id given in the term_ids param does not exist it will be mapped to Null.

services/grades/update_grade

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: required Scopes: n/a SSL: not required
https://usosapps.us.edu.pl/services/grades/update_grade

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Update user's grade.
student_id required ID of user whoose grade will be updated
exam_id required ID of an exam
exam_session_number required number of exam session
value_symbol optional Symbolic value of a grade
comment optional Public comment
private_comment optional Private comment
date_modified optional Date used to avoid concurrency problems. If you expect that grade doesn't exist in database you should pass empty string.
date_acquisition optional Date of grade acquisition.
format optional

Default value: json

Format in which to return values. See supported output formats.
callback optional

Required only if you've chosen jsonp as a return format.
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

An empty dictionary returned if the method has been executed successfully. Some keys may be added in the future.

Thrown errors:

  • object_forbidden - access to object denied.

    Possible reasons:

    • grade_forbidden - access token issuer does not have access to grade;

    • grade_write_forbidden - Access token issuer is not permitted to update grades. Permission rules:

      • course coordinator may update all grades;
      • lecturer may update grates in course unit exam report for participants of lectured groups.
      You need to use another methods to check if user has permissions.

  • object_invalid - object is in invalid state.

    Possible reasons:

    • exam_session_expired - Exam session is currently expired. Updating grades is prohibited;

    • invalid_exam_status - Exam session is not in the state that allows grade modifications.
USOS API ver. 7.1.0.0-4, 0e1fe7fc (2024-08-27)