Accessing information on courses
:: services/courses module

These methods allow you to search for courses and access information on them.

Methods

classtypes_index Get a list of all possible class types.
coordinator Get course editions that user is coordinator of
course Get information on a given course.
course2 Get information on a given course.
course_edition Get information on a given course edition.
course_edition2 Get information on a given course edition.
course_unit Get information on a given unit.
courses Get information on multiple courses.
is_coordinator Is staff member a course edition coordinator.
is_lecturer Is staff member a course edition lecturer.
is_participant Is student participant of course edition.
search Search for courses.
unit Get information on a given unit.
units Get information on multiple course units.
user BETA Get information on user's courses.
user_ects_points Get ECTS points count for user courses

services/courses/classtypes_index

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapi.awf.krakow.pl/services/courses/classtypes_index
Get a list of all possible class types.
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. IDs of class types will be mapped to keys of this dictionary. Each value will contain a description of one class type. Each description is a dictionary of the following structure (currently only one field):

  • name - a LangDict object with the name of the class type.

services/courses/coordinator

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

Get course editions that user is coordinator of
user_id optional

Default value: (access token issuer)

ID of a user.
active_terms_only optional

Default value: true

If true, only course editions from active academic terms will be returned
fields optional

Default value: course|term

Selector of result fields you are interested in. The selector must contain subset of primary fields, which are described in the returns section of course_edition2 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 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:

List of course editions

services/courses/course

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapi.awf.krakow.pl/services/courses/course

Get information on a given course.
course_id required

Pipe-separated list of course IDs.
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:

  • Primary:

    • id - ID of a course.;

    • name - a LangDict object with the course's name;

    • homepage_url - course's homepage URL (or null if none);

    • profile_url - course's profile URL;

    • is_currently_conducted - boolean, indicates if the course is conducted in one of active academic terms;

    • terms - list of academic terms the course was conducted in.

      List of academic terms the course was conducted in. Currently only id of the term is returned. List is sorted by terms order from newest to oldest.

    • fac_id - ID of a faculty which runs this course;

    • lang_id - ID of a language in which the course is conducted, or null if language is unknown;

    • ects_credits_simplified - float; number of ECTS credits *usually* rewarded for completing this course, or null if unknown.

      "Usually", because there are many variants and exceptions. For example, students of a specific degree programme may be rewarded a different number of credits. Or, students which plan to study a course in different academic terms, can also be awarded different number of credits. All this means that you SHOULD NOT put much trust in this value.

  • Secondary:

    • description - a LangDict object;

    • bibliography - a LangDict object;

    • learning_outcomes - a LangDict object;

    • assessment_criteria - a LangDict object;

    • practical_placement - a LangDict object;

    • attributes - additional attributes assigned to this course edition.

      A list of dictionaries sorted in the order they should be presented to the user. Each dictionary will contain the following fields:

      • name - a LangDict object, a name of this attribute,

      • values - a list of LangDict objects, which represent the content of this attribute.

        If the list contains only a single element, the you may assume that it's safe to display it as a paragraph. If it contains many elements, then you should display them a separate list entries (e.g. using bullets).

    • attributes2 - additional attributes assigned to this course edition.

      A list of dictionaries sorted in the order they should be presented to the user. Each dictionary will contain the following fields:

      • name - a LangDict object, a name of this attribute,

      • values - a list of objects, which represent the content of this attribute. Each object could be one of following

        If the list contains only a single element, the you may assume that it's safe to display it as a paragraph. If it contains many elements, then you should display them a separate list entries (e.g. using bullets).

services/courses/course2

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapi.awf.krakow.pl/services/courses/course2

Get information on a given course.
course_id required

Pipe-separated list of course IDs.
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:

  • Primary:

    • id - ID of a course.;

    • name - a LangDict object with the course's name;

    • homepage_url - course's homepage URL (or null if none);

    • profile_url - course's profile URL;

    • description - a LangDict object;

    • bibliography - a LangDict object;

    • learning_outcomes - a LangDict object;

    • assessment_criteria - a LangDict object;

    • practical_placement - a LangDict object.

  • Secondary:

services/courses/course_edition

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

Get information on a given course edition.
course_id required ID of a course
term_id required ID of an academic term
fields optional

Default value: course_id|course_name|term_id|user_groups

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_id - ID of a parent course,;

    • course_name - a LangDict object with the name of a parent course,;

    • term_id - ID of a term,;

    • homepage_url - course edition's homepage URL (or null if none),;

    • profile_url - course's profile URL (or null if none).;

    • coordinators - an array of dictionaries describing coordinators of this course edition; each dictionary contains fields from primary section in users/user method;

    • lecturers - an array of dictionaries describing lecturers of this course edition; each dictionary contains fields from primary section in users/user method;

    • passing_status - one of following values: passed, failed, not_yet_passed;

    • user_groups - Access token issuer's groups.

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

      Additional permissions note: Access token is required, and SSL connection is required.

  • Secondary:

    • description - a LangDict object.;

    • bibliography - a LangDict object.;

    • notes - a LangDict object.;

    • course_units_ids - an array of course edition's units IDs;

    • participants - an array of dictionaries describing listeners of this course edition; each dictionary contains fields from primary section in users/user method;

    • grades - Access token issuer's grades.

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

    • attributes - additional attributes assigned to this course edition.

      A list of dictionaries sorted in the order they should be presented to the user. Each dictionary will contain the following fields:

      • name - a LangDict object, a name of this attribute,

      • values - a list of LangDict objects, which represent the content of this attribute.

        If the list contains only a single element, the you may assume that it's safe to display it as a paragraph. If it contains many elements, then you should display them a separate list entries (e.g. using bullets).

Thrown errors:

  • object_forbidden - access to object denied.

    Possible reasons:

    • participants - access token issuer doesn't have access to list of participants.

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

    Possible reasons:

    • course_edition - referenced course edition does not exist.

services/courses/course_edition2

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

Get information on a given course edition.
course_id required ID
term_id required ID
fields optional

Default value: course|term

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

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

    • term - Term.

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

    • homepage_url - course edition homepage URL (or null if none);

    • description - a LangDict object.;

    • bibliography - a LangDict object.;

    • notes - a LangDict object..

  • Secondary:

    • course_units - Course units of this course_edition.

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

services/courses/course_unit

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

Get information on a given unit.
course_unit_id required ID of a course unit
fields optional

Default value: id

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:

    • id - unit's ID;

    • homepage_url - unit's homepage URL (or null if none);

    • profile_url - unit's profile URL;

    • learning_outcomes - a LangDict object,;

    • assessment_criteria - a LangDict object,;

    • topics - a LangDict object,;

    • teaching_methods - a LangDict object,;

    • bibliography - a LangDict object..

  • Secondary:

    • course_edition - Course edition.

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

    • class_groups - Groups.

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

services/courses/courses

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

Get information on multiple courses.

This method is similar to the course method, but it works with multiple courses. It also has a limited fields support.
course_ids required

Pipe-separated list of course IDs.
fields optional

Default value: id|name

Selector of result fields you are interested in. The selector must contain subset of primary fields, which are described in the returns section of course 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 course_ids will be mapped to dictionary's keys, and each value will contain the description of a course, as defined in the course method.

services/courses/is_coordinator

Consumer: optional Token: optional Scopes: n/a SSL: not required
https://usosapi.awf.krakow.pl/services/courses/is_coordinator
Is staff member a course edition coordinator.
course_id required ID of a course unit (first part of primary key).
term_id required ID of a term (second part of primary key).
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.

services/courses/is_lecturer

Consumer: optional Token: optional Scopes: n/a SSL: not required
https://usosapi.awf.krakow.pl/services/courses/is_lecturer
Is staff member a course edition lecturer.
course_id required ID of a course unit (first part of primary key).
term_id required ID of a term (second part of primary key).
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

services/courses/is_participant

Consumer: required Token: required Scopes: none SSL: not required
https://usosapi.awf.krakow.pl/services/courses/is_participant
Is student participant of course edition.
course_id required ID of a course unit.
term_id required ID of a term.
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 user is participant of that course edition.
Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapi.awf.krakow.pl/services/courses/search

Search for courses matching given query.
lang required A code of the preferred language ("pl" or "en"). It will influence the order and other display properties of the returned matches.
name optional Course name (or part of it). USOS API will match this against names and IDs of courses.
fields optional

Default value: course_id|match

Pipe-separated list of fields. See the returned value section below for the list of available fields.
num optional

Default value: 6

Identifies the number of search results to return. The maximum value of num is 20.
start optional

Default value: 0

Indicates the first matching result that should be included in the search results. This parameter uses a zero-based index, meaning the first result is 0, the second result is 1 and so forth.

Note, that no more than 100 search result will ever be returned for any query, even if more than 100 matches were found. If you need more, than probably you're looking at a wrong method. Contact us if you're not sure.
fac_id optional A faculty ID. If given, it restricts the search to courses run by this faculty.
fac_deep optional

Default value: false

Boolean. Valid only when used along with the fac_id parameter. By default, fac_id restricts the search to courses run ONLY by a given faculty. Set fac_deep to "true" in order to also include courses run by subfaculties of this faculty.
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 the following structure:

  • items - a list of matching courses. The length of this list is limited to num items. You can access further results by specifing the start parameter.

    Each item on this list is a dictionary of selected fields. Only primary fields described in the course method are allowed plus two more:

    • course_id - same as id. Left for backward compatibility.

    • match - a string with matching fragments highlighted with HTML <b> tag. Language used in construction of this string may vary - you may not assume it will always be your preferred language. It also may include the course ID (if we think it's relevant).

  • next_page - boolean, indicates if there is a next page of results for this query.

services/courses/unit

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

Get information on a given unit.
unit_id required ID of a unit.
fields optional

Default value: id

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:

    • id - unit's ID;

    • course_name - a LangDict object with the name of a parent course;

    • course_id - ID of a parent course;

    • term_id - ID of the term of a parent course edition;

    • homepage_url - unit's homepage URL (or null if none);

    • profile_url - unit's profile URL;

    • classtype_id - ID of the unit's class type.

  • Secondary:

    • learning_outcomes - a LangDict object;

    • assessment_criteria - a LangDict object;

    • topics - a LangDict object;

    • teaching_methods - a LangDict object;

    • bibliography - a LangDict object;

    • groups - List of groups of this unit.

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

services/courses/units

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

Get information on multiple course units.

This method is similar to the unit method, but it works with multiple units. It also has a limited fields support.
unit_ids required Pipe-separated list of unit IDs.
fields optional

Default value: id

Selector of result fields you are interested in. The selector must contain subset of primary fields, which are described in the returns section of unit 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 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 unit_ids will be mapped to dictionary's keys, and each value will contain the description of a course, as defined in the unit method (or null if the given unit_id has not been found).

services/courses/user

Consumer: required Token: required Scopes: none SSL: not required
https://usosapi.awf.krakow.pl/services/courses/user

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 information on user's courses.
fields optional

Default value: course_editions

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

active_terms_only optional

Default value: true

Return only these course editions 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 of selected fields and their values.

Available fields:

  • course_editions - Dictionary mapping an academic terms to array of dictionaries describing course editions.

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

  • terms - List of Academic Terms.

    A list of Academic Terms referenced (by ID) in course_editions section sorted anti-chronologically. Format will be the same as in the terms/terms method.

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

services/courses/user_ects_points

Consumer: required Token: required Scopes: none SSL: not required
https://usosapi.awf.krakow.pl/services/courses/user_ects_points

Get ECTS points count for user courses
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:

Map from term IDs to map from course IDs to ECTS point count as string or null if ECTS for this course could not be calculated.
USOS API ver. 7.1.0.0-4, 0e1fe7fc, dirty (2024-08-27)