Accessing activity timetables
:: services/tt module

These methods allow you to access timetables of various university-related events, such like:

  • A list of student activities (lectures, tutorials, exams etc.).
  • A list of teacher activities (classes instructed).
  • A list of all activities related to a single course unit.
  • etc.

Some examples of usage:

  • Use these to display schedules in various formats on various devices.
  • Convert timetables to other formats.
  • A javascript snippet which can be embedded on any webpage and would display a current timetable for a given course unit.
  • Synchronize data with a desktop and web calendar apps.

Methods

classgroup Get activities related to single class group.
classgroup_dates Get dates of all activities related to a class group.
classgroup_dates2 Get all activities related to a class group.
classgroups Get activities related to given class groups.
course_edition Get all activities related to a specified course edition.
course_editions Get all activities related to specified course editions.
room Get activities for a given room.
staff Get public staff member's activities.
student Get activities related to user's studies.
upcoming_ical Get iCalendar file with the user's upcoming events
upcoming_share Get the webcal feed of the user's upcoming events
user Get all activities related to the user.

services/tt/classgroup

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/tt/classgroup
Get activities related to single class group. Usually one class group meets up once a week at specified hours, but there's no any real rule for that.
unit_id required ID of class group's "parent" course unit.
group_number required Group number of the class.
start optional

Default value: today

A date string, yyyy-mm-dd format. A first (earliest) day to include in the results.
days optional

Default value: 7

Number of days (starting with start) to include in the results. No more than 7 is allowed.
fields optional

Default value: start_time|end_time|name

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 list of Activity objects.

Each Activity object is a dictionary of fields. There are different types of Activity objects, these are the fields they all have in common:

  • type - type of activity. Currently there are three possible values: classgroup, classgroup2, meeting or exam.

    Important: more activity types may be introduced in the future. Your application should expect that.

  • start_time - datetime string ("yyyy-mm-dd hh:mm:ss" format, local time), indicates the moment in time when the activity starts,
  • end_time - datetime string ("yyyy-mm-dd hh:mm:ss" format, local time), indicates the moment in time when the activity ends.
  • name - a LangDict object with a generic name for this activity - use it whenever you don't want to, or don't know how to build your own (i.e. when you receive an unknown activity type).
  • url - a generic URL for this activity OR null, if there is no such URL.

Depending on type of the activity, some "extra" fields become available:

  • If type equals "classgroup":

    Such activity data is derived from some complex data structures describing class groups and their meeting schedules (you may see the derivation path on this diagram). Specific activity dates are determined automatically by taking into account the frequency of classes and days off. Be aware: for classes with frequency "other" or "once" there is no way do determine a specific date. For such cases all possible days in an academic term will be returned.

    Following "extra" fields are available:

    • course_id - ID o a course of this class,
    • course_name - a LangDict object with the name of a course,
    • classtype_name - a LangDict object with the name of a class type (example: {"pl": "Wyklad", "en": "Lecture"}),
    • lecturer_ids - list of user IDs, these reference the staff members which are the lecturers of this class (warning: for backward compatibility, this will be a list of integers, not strings!),
    • group_number - group number of this class,
    • classgroup_profile_url - URL of a "profile page" of this class group (a page users can get more info on this specific class),
    • building_name - a LangDict object with the name of a building, or empty LangDict if unknown,
    • building_id - building ID, or null if unknown,
    • room_number - number of the room (e.x. "203B"), or empty string if unknown,
    • room_id - room ID, or null if unknown
    • unit_id - ID of a course unit.
    • classtype_id - ID of a "class type" entity.
    • cgwm_id - ID of a "class group weekly meeting" entity.
    • frequency - string, a "frequency code", indicates frequency of classes. Possible values include: every_fortnight, every_fortnight_odd, every_fortnight_even, every_month, every_week, every_working_day, every_weekend, every_day, other, once (other codes may be added in future, be prepared for this!). USOS API uses this frequency to determine specific activity dates. Despite that it is a good practice to inform users of classes frequency. For some types of frequency (ex. other, once) it is not possible to determine a specific date (see method description).

  • If type equals "classgroup2":

    This type looks almost like "classgroup", but the data is collected by other means (diagram). Activities of this type are confirmed meetings (unlike "classgroup" activities, they are NOT automatically generated).

    Following "extra" fields are available:

    • all extra fields mentioned in the "classgroup" section except the frequency field,
    • sm_id - ID of a "single meeting" entity.

  • If type equals "meeting":

    This type of activity is not related to any specific class group, but some other methods (like the room method) may include it in the result.

    Following "extra" fields are available:

    • related_user_ids - list of IDs of users (most probably, staff members) which are the best estimation of who can be contacted in regard of this activity.

  • If type equals "exam":

    This type of activity is related to course exams. Related data may be retrieved using module services/exams.

    Following "extra" fields are available:

    • course_id - ID o a course of this class,
    • course_name - a LangDict object with the name of a course,
    • group_number - group number of this exam,
    • slot_number - if student is registered to particular slot, its number is returned, or null in any other case
    • building_id - building ID, or null if unknown,
    • building_name - a LangDict object with the name of a building, or empty LangDict if unknown,
    • room_number - number of the room (e.x. "203B"), or empty string if unknown,
    • room_id - room ID, or null if unknown

Please note, that you may receive more fields than you specified. Still, you may not expect to receive fields you did not specify.

services/tt/classgroup_dates

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/tt/classgroup_dates

This is an older version of classgroup_dates method. It takes the same parameters, but it returns dates only. Also, some of the dates with "unsure" frequency are removed from the results.
unit_id required ID of class group's "parent" course unit.
group_number required Group number of the class.
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 strings. Each string is a date in the "YYYY-MM-DD" format.

services/tt/classgroup_dates2

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/tt/classgroup_dates2

Other methods have a limit workspan of 7 days. This one does not, but it is limited to a single classgroup (and it takes no timeframe-related arguments). It gives you a full list of activities related to a single classgroup.
unit_id required ID of class group's "parent" course unit.
group_number required Group number of the class.
fields optional

Default value: start_time|end_time|name

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 list of Activity objects, as in the classgroup method.

services/tt/classgroups

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/tt/classgroups
Get activities 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.
classgroup_ids required Pipe-separated list of class group IDs. Since there's no such thing as a class group ID (each class group is identified by two columns, not one!), we have to develop one for the purpose of this argument. Class group ID is "unit_id|group_number", where unit_id and group_number are keys which identify the class group (you'll get something like "unit|group|unit|group|..." etc.).
partial optional

Default value: false

If set to true, response will be wrapped with PartialResponse object. This will allow invalid references to be treated as warnings, instead of errors.
start optional

Default value: today

A date string, yyyy-mm-dd format. A first (earliest) day to include in the results.
days optional

Default value: 7

Number of days (starting with start) to include in the results. No more than 7 is allowed.
fields optional

Default value: start_time|end_time|name

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 list of Activity objects, as in the classgroup method.

services/tt/course_edition

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/tt/course_edition
Get all activities related to a specified course edition. This includes ALL activities of ALL class groups of this course.
course_id required ID of the course.
term_id required ID of the term during which the course edition is run.
start optional

Default value: today

A date string, yyyy-mm-dd format. A first (earliest) day to include in the results.
days optional

Default value: 7

Number of days (starting with start) to include in the results. No more than 7 is allowed.
fields optional

Default value: start_time|end_time|name

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 list of Activity objects, as in the classgroup method.

services/tt/course_editions

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/tt/course_editions
Get all activities related to specified course editions. This method is similar to the course_edition method, but it works with multiple editions.
course_edition_ids required Pipe-separated list of course edition IDs. Since there's no such thing as a course edition ID (each course edition is identified by two columns, not one!), we have to develop one for this purpose. Course Edition ID is "course_id|term_id", where course_id and term_id are keys which identify the course_edition (you'll get something like "course|term|course|term|..." etc.).
partial optional

Default value: false

If set to true, response will be wrapped with PartialResponse object. This will allow invalid references to be treated as warnings, instead of errors.
start optional

Default value: today

A date string, yyyy-mm-dd format. A first (earliest) day to include in the results.
days optional

Default value: 7

Number of days (starting with start) to include in the results. No more than 7 is allowed.
fields optional

Default value: start_time|end_time|name

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 list of Activity objects, as in the classgroup method.

services/tt/room

Consumer: required Token: ignored Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/tt/room
Get activities which take place in a given room.
room_id required ID of the room.
start optional

Default value: today

A date string, yyyy-mm-dd format. A first (earliest) day to include in the results.
days optional

Default value: 7

Number of days (starting with start) to include in the results. No more than 7 is allowed.
fields optional

Default value: start_time|end_time|name

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 required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Token is not required.

Returned value:

A list of Activity objects, as in the classgroup method.

services/tt/staff

Consumer: optional Token: optional Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/tt/staff
Get public activities related to 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).
user_id optional ID of a staff member. Required, if you don't sign your request with a proper Access Token.
start optional

Default value: today

A date string, yyyy-mm-dd format. A first (earliest) day to include in the results.
days optional

Default value: 7

Number of days (starting with start) to include in the results. No more than 7 is allowed.
fields optional

Default value: start_time|end_time|name

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 list of Activity objects, as in the classgroup method.

services/tt/student

Consumer: required Token: required Scopes: studies SSL: not required
https://usosapi.panschelm.edu.pl/services/tt/student
Get activities 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.
start optional

Default value: today

A date string, yyyy-mm-dd format. A first (earliest) day to include in the results.
days optional

Default value: 7

Number of days (starting with start) to include in the results. No more than 7 is allowed.
fields optional

Default value: start_time|end_time|name

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 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 Activity objects, as in the classgroup method.

services/tt/upcoming_ical

Consumer: optional Token: optional Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/tt/upcoming_ical

Get iCalendar file with the user's upcoming events.

This method can be accessed anonymouosly so that it can be used with the webcal scheme. If you don't have the key, then it has to be accessed with the Access Token and the "studies" scope.

Upcoming events include only those events which are in near future. Events in the past and events in the far future will not be included. The exact definition of "near future" is left undocumented (and may change in time).
user_id required ID of the user. (If you use an Access Token, then it has to match this user.)
lang required Preferred language of the calendar and its entries. This should be either pl or en.
key optional

Default value: (empty string)

Optional secret key generated for this user. Use the upcoming_share method to retrieve it.

If key is provided, then no other authentication is required. If you have the key, then you may access this method anonymously.
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:

HTTP 200 response with the iCalendar file.

services/tt/upcoming_share

Consumer: required Token: required Scopes: studies SSL: not required
https://usosapi.panschelm.edu.pl/services/tt/upcoming_share

Get the webcal feed of the user's upcoming events.

Use this method to get the webcal URI needed to import user's upcoming events into external applications.
lang required Preferred language of the calendar and its entries. This should be either pl or en.
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 following fields and their values:

  • webcal_url - an URI with the webcal scheme.

services/tt/user

Consumer: required Token: required Scopes: studies SSL: not required
https://usosapi.panschelm.edu.pl/services/tt/user
Get all activities related to the user. This is like joining student and staff methods in one.
start optional

Default value: today

A date string, yyyy-mm-dd format. A first (earliest) day to include in the results.
days optional

Default value: 7

Number of days (starting with start) to include in the results. No more than 7 is allowed.
fields optional

Default value: start_time|end_time|name

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 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 Activity objects, as in the classgroup method.
USOS API ver. 7.1.0.0-4, 0e1fe7fc (2024-08-27)