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 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.
update_grade BETA Update user's grade. (administrative)

services/grades/course_edition

Consumer: required Token: required Scopes: grades SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

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|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 - Dictionary describing grades related to course edition's main exam. Returned dictionary 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/exam

Consumer: required Token: required Scopes: grades SSL: not required
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

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|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
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

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|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;

    • 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;

    • 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.

    • 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
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

Get info about grade type.

grade_type_id required Identifier of the type.
fields optional

Default value: id|name

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;

  • 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/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
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

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.
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. 6.1.2.0-bc1aa53 (2016-06-07)