Course groups and their participants
:: services/groups module

These methods allow you to access information on course groups. It is also possible to get a list of groups user is participating in.

Note, that this module will be probably deprecated in the future, mainly because it uses invalid vocabulary (e.g. "course groups" instead of "classgroups"), and it doesn't support a subfield selector. The methods will keep working though.

Methods

class_group Get information on a given group.
common_groups BETA Get a list of common classgroups of two users
group Get information on a given group.
groups Get information on multiple groups.
is_lecturer Is user a group lecturer.
is_participant Is student participant of the group.
lecturer Get public list of groups lectured by given staff member.
participant Get groups related to given user's study
user Get all groups related to the user.

services/groups/class_group

Consumer: optional Token: optional Scopes: n/a SSL: required
https://usosapi.awf.krakow.pl/services/groups/class_group

Get information on a given group.
course_unit_id required ID of course unit
group_number required Group number
fields optional

Default value: course_unit_id|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 optional standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • Primary:

    • course_unit_id - ID of the course unit related to the group,;

    • number - number of the group unique with regard to the course unit,;

    • url - group homepage URL (or null if none),;

    • description - a LangDict;

    • literature - a LangDict object.

  • Secondary:

    • course_unit - Class unit related to this class group.

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

    • lecturers - group lecturers.

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

    • participants - group participants.

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

services/groups/common_groups

Consumer: required Token: required Scopes: studies SSL: not required
https://usosapi.awf.krakow.pl/services/groups/common_groups

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.

Get a list of common classgroups of two users.

One of these users is the issuer of your Access Token, the other is the one provided in the user_id parameter. This method will return all the classgroups that these two users have both participated or lectured at. Some extra metadata will be returned along the classgroups (see the returns section).
user_id required ID of the "other" user
fields required

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 list of dictionaries. Each dictionary will contain the following fields:

  • group - a classgroup object.

    Use a subfield selector to indicate which fields of the group object you want. You may access only the primary fields.

    This field references objects returned by group method. See its returns section for possible subfields.

  • my_role - Access Token's issuer's role in this classgroup.

    Either participant or lecturer.

  • his_role - other user's role in this classgroup.

    Either participant or lecturer.

services/groups/group

Consumer: optional Token: optional Scopes: n/a SSL: not required
https://usosapi.awf.krakow.pl/services/groups/group
Get information on a given group.
course_unit_id required ID of a course unit.
group_number required Group number unique with regard to the course unit.
fields required Pipe-separated list of informational fields/sections you're interested in. This must be any subset of keys, 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 optional standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization.

Returned value:

A dictionary of selected result fields and their values.

Available fields:

  • Primary:

    • course_unit_id - ID of the course unit related to the group,
    • group_number - number of the group unique with regard to the course unit,
    • class_type - a LangDict object identyfing class type,
    • class_type_id - class type id,
    • group_url - group homepage URL (or null if none),
    • course_id - course ID,
    • course_name - a LangDict object with the courses name,
    • course_homepage_url - courses homepage URL (or null if none),
    • course_profile_url - courses profile URL,
    • course_is_currently_conducted - boolean, indicates if the course is conducted in one of active academic terms,
    • course_fac_id - ID of a faculty which runs this course.
    • course_lang_id - ID of a language in which the course is conducted, or null if language is unknown.
    • term_id - ID of academic term to which this group is related.
    • lecturers - an array of dictionaries describing lecturers of this group; each dictionary contains fields from primary section in services/users/user method
    • participants - an array of dictionaries describing participants of this group; each dictionary contains fields from primary section in services/users/user method.
      Additional permissions note: Access Token with the 'studies' scope required (or administrative access). Note that only lecturer or participant can ask for group participants.

  • Secondary:

    • group_description - a LangDict object.
    • group_literature - a LangDict object.
    • course_learning_outcomes - a LangDict object.
    • course_description - a LangDict object.
    • course_bibliography - a LangDict object.
    • course_assessment_criteria - a LangDict object.
    • course_practical_placement - a LangDict object.

services/groups/groups

Consumer: optional Token: optional Scopes: n/a SSL: not required
https://usosapi.awf.krakow.pl/services/groups/groups

Get information on multiple groups.

This method is similar to the group method, but it works with multiple groups. It also has a limited fields support.
group_ids required Pipe-separated list of pairs identyfing groups (in the following format: "(course_unit_id,group_number)|...").
fields required Pipe-separated list of fields (as in the group method). Only primary fields are allowed.
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 optional standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization.

Returned value:

A dictionary: your group_ids will be mapped to dictionary's keys, and each value will contain the description of a group, as defined in the group method.

services/groups/is_lecturer

Consumer: optional Token: optional Scopes: n/a SSL: not required
https://usosapi.awf.krakow.pl/services/groups/is_lecturer
Is user a group lecturer.
course_unit_id required ID of a course unit.
group_number required Group number unique with regard to the course unit.
user_id optional

Default value: access token issuer.

ID of a user.
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 optional standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization.

Returned value:

Boolean value - true if user corresponds to Access Token is lecturer of the group, false otherwise.

services/groups/is_participant

Consumer: required Token: required Scopes: none SSL: not required
https://usosapi.awf.krakow.pl/services/groups/is_participant
Is student participant of the group.
course_unit_id required ID of a course unit.
group_number required Group number unique with regard to the course unit.
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:

Boolean value - true if student participates in the group.

services/groups/lecturer

Consumer: optional Token: optional Scopes: n/a SSL: not required
https://usosapi.awf.krakow.pl/services/groups/lecturer
Get public list of groups lectured by given staff member. Public means, that you may anonymously access such activities of ALL staff members, you don't need their approval for this (teachers' schedules are publicly available).
fields required Pipe-separated list of fields (as in the group method). Only primary fields are allowed.
user_id optional

Default value: access token issuer.

ID of a user.
lang optional

Default value: pl

Either pl or en - resulting list of groups will be sorted by the course name in the specified language.
active_terms optional

Default value: false

Return only these groups which are related to the currently active academic terms.
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 optional standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization.

Returned value:

The same as defined in participant method.

services/groups/participant

Consumer: required Token: required Scopes: studies SSL: not required
https://usosapi.awf.krakow.pl/services/groups/participant

Get groups related to given user's study.

This means, that if the user is also a staff member, then this method will NOT include entries related to his staff-activities.
fields required Pipe-separated list of fields (as in the group method). Only primary fields are allowed.
lang optional

Default value: pl

Either pl or en - resulting list of groups will be sorted by the course name in the specified language.
active_terms optional

Default value: false

Return only these groups which are related to the currently active academic terms.
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 with the following fields:

  • groups - a dictionary mapping an Academic Term to an array of dictionaries as defined in the group method sorted by the course name in the specified language.

  • terms - a list of academic terms referenced (by ID) in the exams section sorted anti-chronologically. Format will be the same as in the terms/terms method.

services/groups/user

Consumer: optional Token: optional Scopes: n/a SSL: not required
https://usosapi.awf.krakow.pl/services/groups/user
Get all groups related to the user. This is like joining participant and lecturer methods in one.
fields required Pipe-separated list of fields (as in the group method). Only primary fields are allowed.
lang optional

Default value: pl

Either pl or en - resulting list of groups will be sorted by the course name in the specified language.
active_terms optional

Default value: false

Return only these groups which are related to the currently active academic terms.
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 optional standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization.

Returned value:

The same as defined in participant method extended by field relationship_type - which determines the relationship between the token issuer (if available) and this group (allowed values are: participant, or lecturer).
USOS API ver. 7.1.0.0-4, 0e1fe7fc, dirty (2024-08-27)