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.
course Get information on a given course.
course_edition Get information on a given course edition.
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.

services/courses/classtypes_index

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 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/course

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 information on a given course.
course_id required ID of a course.
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.
No additional OAuth arguments are required. If you provide any, they will be ignored.

Returned value:

A dictionary of selected result fields and their values.

Available fields:

  • Primary:

    • id - course's ID,
    • 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,
    • 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.
  • Secondary:

    • description - a LangDict object.
    • bibliography - a LangDict object.
    • learning_outcomes - a LangDict object.
    • assessment_criteria - a LangDict object.
    • practical_placement - a LangDict object.

services/courses/course_edition

Consumer: optional Token: optional 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 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

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.

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

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/courses

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 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 required Pipe-separated list of fields (as in the course 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.
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
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.
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
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.
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
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.
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
URLs of the methods are hidden, because this installation is the mother server.
Click here for the list of all public USOS API installations.

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.
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 the following structure:

    • course_id - ID of a course,
    • 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
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 information on a given unit.
unit_id required ID of a 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:

    • 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. Each item of this list will have same structure as the result of the group method.

services/courses/units

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 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 required Pipe-separated list of fields (as in the unit 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.
No additional OAuth arguments are required. If you provide any, they will be ignored.

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

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.

USOS API ver. 6.1.2.0-bc1aa53 (2016-06-07)