Study programmes
:: services/progs module

These methods allow you to access information regarding study programmes.

Methods

programme Get information on a given study programme.
programmes Get information on multiple study programmes.
search Search for programmes.
search_history_affect Add a programme to search history.
stage Get stage info
student Get information on student programmes of a given user.
student_programme Get information on a given student programme.
student_programmes Get information on multiple student programmes.

services/progs/programme

Consumer: optional Token: ignored Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/progs/programme

Get information on a given study programme.
programme_id required

ID of a programme.
fields optional

Default value: id|description

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. Token is not required.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • id - ID of the programme;

  • name - a LangDict object with the name of the programme;

  • description - again, a LangDict object with the name of the programme.

    This field is deprecated because its name was misleading. It does not contain the description of the programme. Its value is very short and contains only the name of the programme. Currently it is an alias of the name field.

  • faculty - a faculty object, or null.

    This is the faculty which administers this study programme. The object is of the same structure as the one described in the services/fac/faculty method. If no faculty administers this programme, then null will be returned.

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

  • all_faculties - a faculty object, or null.

    List of faculties related to programme.

  • mode_of_studies - a LangDict object with a short, human-readable representation of the studies-mode provided by the programme (e.g. full-time);

  • level_of_studies - a LangDict object with a short, human-readable representation of the level of the programme (e.g. first cycle programme);

  • duration - a LangDict object with a short, human-readable representation of the duration of the programme (e.g. 3-year studies);

  • professional_status - a LangDict object with the description of qualifications that will be acquired after graduation from this programme;

  • level - One of following values: first_cycle, second_cycle, third_cycle, phd_school, long_cycle.

Thrown errors:

  • object_not_found - some of the referenced objects do not exist; param_name is equal to programme_id.

services/progs/programmes

Consumer: optional Token: ignored Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/progs/programmes

Get information on multiple stidy programmes at once.
programme_ids required

List of programme IDs.
fields optional

Default value: id|description

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section of programme 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. Token is not required.

Returned value:

A dictionary.

  • Your programme_ids will be mapped to the keys of the dictionary.
  • The values will be either null (if the programme doesn't exist), or a dictionary in the same format as the one returned in the programme method.
Consumer: optional Token: optional Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/progs/search

Search for programmes matching the given query and/or filters.

USOS API supports personalized search results. For example, it may display certain items higher in the results, based on personal user preferences and connections. You should include Access Tokens in your requests in order to make use of these features. For best results, you should also use the search_history_affect method.
lang required

A code of the preferred language ("pl" or "en"). It may influence the order and other properties of the returned matches (in particular, the language used in the match field).
fields optional

Default value: items[programme[id]|match]|next_page

A selector of result fields you are interested in.
query optional

Default value: (empty string)

The search query. The most obvious value for this field is the programme title, but we'll try to be smart about it.
num optional

Default value: 6

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

Default value: 0

Zero-based offset of the first item that should be included in the response. (Or, in other words, the number of items to strip from the beginning of the items-list.)

Note, that currently no more than 100 items will be returned for any query, even if more than 100 matches were found.
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:

  • items - a list of items which have matched your query.

    The length of this list is limited to num items. You can access further results by specifying the start argument.

    Each item on this list is a dictionary of the following structure (you can choose more fields with a subfield selector):

    • programme - the programme object, as described in the programme method.

    • match - programme name with matching fragments highlighted with HTML <b> tag.

      The match may also contain other content, depending on your query, e.g. programme ID.

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

services/progs/search_history_affect

Consumer: required Token: required Scopes: none SSL: not required
https://usosapi.panschelm.edu.pl/services/progs/search_history_affect

Add a programme to search history.

This method aims at improving user experience while searching. Call this method once your user visits programme's page, or when he/she selects a programme while searching for prorgammes, etc.

Given programme will be added to search history. Items saved in search history may appear more frequently in search results.
programme_id required

The ID of the programme you want saved to the search history.
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:

Currently, it always returns {"success": true}.

services/progs/stage

Consumer: ignored Token: ignored Scopes: n/a SSL: required
https://usosapi.panschelm.edu.pl/services/progs/stage

Get stage info
id required ID of a stage
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 - ID of a stage;

  • name - Langdict.

services/progs/student

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

This is similar to the student_programmes field of the services/users/user method, but allows you to explicitly decide if you want only the active student programmes.
user_id optional

Default value: (access token issuer)

ID of a user.
fields optional

Default value: id|programme

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

active_only optional

Default value: true

By default, you will get only student programmes with the status equal to active or graduated_before_diploma. Set this to false if you want to include all student programmes. Please note, that only these student programmes which you have access to will be included. And even if you have access to a student programme, some of its fields may still be hidden (see the student_programme method for details).
old_programs optional

Default value: true

Get only programs which ended in past
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 optional oauth_token for Token authorization.

Returned value:

List of student_programme objects.

services/progs/student_programme

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

Get information on a given student programme.

Visibility of the fields depends on many variables which are not publicly documented. However, some general rules apply:

  • You should always provide an Access Token (if you have one).

  • If you want to have access to more objects and fields, then you should probably ask your users for the studies scope.
  • Active students are "more visible" than inactive ones (more fields can be read without the Access Token).
  • Staff members have "more access" than users outside of staff. (However, you might need to gain access to some specific scopes before you'll be able to see it.)
student_programme_id required

ID of a student programme.

If the student programme does not exist or you don't have the access to view it, you will get a HTTP 400 response.
fields optional

Default value: id|programme

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 optional oauth_token for Token authorization.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • id - ID of the student programme.;

  • user - an object describing the user of this student_programme;

  • programme - an object describing the programme.

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

  • status - status of the student programme.

    If you don't have access to read this field, you will receive null. If you do have access, then it will be a string - one of the following codes:

    • active - the student is currently studying on this programme,
    • cancelled - the student has been removed from this programme,
    • graduated_end_of_study - the student has successfully graduated the programme, and the programme doesn't end with a diploma exam,
    • graduated_before_diploma - the student has successfully graduated the programme, and the programme does end with a diploma exam, but the student didn't pass this exam yet,
    • graduated_diploma - the student has successfully graduated the programme, and the programme does end with a diploma exam, and the student did pass this exam.

  • admission_date - date of admission of a student on this programme or null if it is unknown or you don't have access to see this field;

  • stages - List of stages for acquired progamms;

  • is_primary - True if this programme is marked as his/her primary programme.

Thrown errors:

  • object_not_found - some of the referenced objects do not exist; param_name is equal to student_programme_id.

services/progs/student_programmes

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

Get information on a multiple student programmes at once.
student_programme_ids required

Pipe-separated list of student programme IDs.
fields optional

Default value: id|programme

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section of student_programme 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 optional oauth_token for Token authorization.

Returned value:

A dictionary.

  • Your student_programme_ids will be mapped to the keys of the dictionary.

  • The values will be either:

    • null - if the student programme does not exist or you don't have access to it,
    • a dictionary in the same format as the one returned in the student_programme method.
USOS API ver. 7.1.0.0-4, 0e1fe7fc (2024-08-27)