Theses and diplomas
:: services/theses module

This module allows you to access information on theses, their authors and supervisors. It also allows you to search for theses.

Currently, this module is pretty simple. More features may be added if needed. Contact us!

A note for USOS developers: This module "flattens" the representations of four USOS tables into two simpler, dynamically rendered "joint entities" (see attached image). We believe that this representation is better suited for a public API and that all differences between actual USOS entities can be expressed with additional dynamic attributes (e.g. the "type" field of the thesis entity).

Methods

authorship_preference Get information about whether users prefer sharing their theses' authorship. (administrative)
exam_report BETA Get diploma exam report.
exam_reports BETA Get information on multiple exam reports.
search Search for theses.
search_history_affect Add a thesis to search history.
sign_report BETA Sign the exam report.
signable_reports BETA Get diploma exam reports that can get signed by user.
theses Get information on multiple theses.
thesis Get information on a single thesis.
user Get theses-related information on a given user.
users Get theses-related information on multiple users.

services/theses/authorship_preference

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: ignored Scopes: n/a SSL: required
https://usosapi.awf.krakow.pl/services/theses/authorship_preference

Get information about whether users prefer sharing their theses' authorship.
user_ids required Pipe-separated list of user IDs. They must be valid user IDs, if they're not, then the results are undetermined - you may get an error, but you may also get fake/invalid values.
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 dictionary: your user_ids will be mapped to dictionary's keys, and each value will be a boolean — true if a person allows to show their authorship for their theses.

services/theses/exam_report

Consumer: required Token: required Scopes: staff_perspective SSL: required
https://usosapi.awf.krakow.pl/services/theses/exam_report

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 diploma exam report.
report_id required ID of the report
fields optional

Default value: id|name|status

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 dictionary of selected fields and their values.

Available fields:

  • id - ID of the exam;

  • name - LangDict, exam name;

  • status - status of the exam.

    Possible values:

    • passed - exam was passed;

    • failed - exam was failed;

    • did_not_sit - examinee did not sit without justification;

    • in_progress - exam is currently in progress;

    • grading - exam is completed, but grading has not completed;

  • theses - list of theses defended in exam.

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

Thrown errors:

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

    Possible reasons:

    • report_not_found - exam report was not found.

services/theses/exam_reports

Consumer: required Token: required Scopes: staff_perspective SSL: required
https://usosapi.awf.krakow.pl/services/theses/exam_reports

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 multiple exam reports.
report_ids required

Pipe-separated list of report IDs.
fields optional

Default value: id|name|status

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

Returned value:

A dictionary: your report_ids will be mapped to dictionary's keys, and each value will contain the description of one exam report, as defined in the exam_report method.

For invalid report_ids (exam reports which do not exist) null will be returned (instead of the exam report object).
Consumer: required Token: optional Scopes: n/a SSL: not required
https://usosapi.awf.krakow.pl/services/theses/search

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

By default, this method will search among all types of theses. If you'd like to search only in a limited subset of them, then try using some of the optional parameters.

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[thesis[id|type|title]|match]|next_page

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

query optional

Default value: (empty string)

The search query. The most obvious value for this field is the thesis title, but we'll try to be smart about it. For example, we can also try to find theses by keywords, or by the names of their authors or supervisors, etc. Keep in mind that these extra searching features are not guaranteed to work in the future.

Also note, that if you're searching by providing the author's name, then some results may be hidden, in accordance to user preferences. Only authors, supervisors and reviewers can see all the theses.
type optional

Default value: all

Pipe-separated list of thesis types among which to search. For the list of allowed values see the type field of the thesis method.

An extra value of all can be used to indicate all available types (this is the default).
fac_ids optional

Default value: (empty string)

Pipe-separated list of faculty IDs. If given, then the results will be limited to only those theses which have been submitted to one of the given faculties.
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 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:

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

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

    • match - thesis title with matching fragments highlighted with HTML <b> tag.

      The match may also contain other text, it is not limited to the the thesis title. For example, if you provide a part of the thesis author's name in your query, then the match may also include the name of the author, etc.

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

services/theses/search_history_affect

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

Add a thesis to search history.

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

Given thesis will be added to search history (currently stored separately for each consumer key and each user). Items saved in search history may appear more frequently in search results.
ths_id required

The ID of the thesis 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/theses/sign_report

Consumer: required Token: required Scopes: theses_protocols_write | staff_perspective SSL: not required
https://usosapi.awf.krakow.pl/services/theses/sign_report

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.

Sign the exam report.
report_id required ID of exam report
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:

Empty dict on success

Thrown errors:

  • object_invalid - object is in invalid state.

    Possible reasons:

    • report_not_signable - report cannot be currently signed;

    • report_signed - report has been already signed.

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

    Possible reasons:

    • report_not_found - exam report was not found.

services/theses/signable_reports

Consumer: required Token: required Scopes: staff_perspective SSL: required
https://usosapi.awf.krakow.pl/services/theses/signable_reports

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 diploma exam reports that can get signed by user.
fields optional

Default value: id|name|status

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

Returned value:

List of exam report object will be returned, as described in exam_report method.

services/theses/theses

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

Get information on multiple theses.
ths_ids required

Pipe-separated list of thesis IDs.
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 of thesis 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 ths_ids will be mapped to dictionary's keys, and each value will contain the description of one thesis, as defined in the thesis method.

For invalid ths_ids (theses which do not exist) null will be returned (instead of the thesis object).

services/theses/thesis

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

Get information on a single thesis.
ths_id required

ID of the thesis.
fields optional

Default value: id|type|title

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 - the ID of the thesis;

  • type - thesis type.

    One of the following values: doctoral, master, licentiate, engineer or postgraduate. Other types may come in the future, you must be ready for them (for example, you should display them as "unknown types").

  • title - string (not a LangDict). The primary title of the thesis.

    Most of USOS entities have at most two names - in Polish and in English. However, theses may have as much as three different titles. This is the primary title. Other titles (in Polish and in English) can be found in the titles fields.

  • titles - LangDict object. Polish and English names of the thesis;

  • language - dictionary. Language of thesis.

    The dictionary currently contains these subfields:

    • code - language code. Note that these codes are set internally by university.

    • iso_code - language code, as specified in ISO 6391, or null if not set.

  • authors - a list of thesis authors.

    Each element of this list is a services/users/user object. You can use a subfield selector to ask for specific user fields (the default is id|first_name|last_name).

  • supervisors - a list of thesis supervisors.

    Each element of this list is a services/users/user object. You can use a subfield selector to ask for specific user fields (the default is id|first_name|last_name).

  • faculty - the faculty to which this thesis has been submitted to.

    This an an object in the formated described in the services/fac/faculty method. You can use a subfield selector to ask for specific faculty fields (the default is id|name).

services/theses/user

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

Get theses-related information on a given user. Visibility of the information may depend on the roles of your user, and scopes provided to you.
user_id required

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

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • authored_theses - the list of all theses authored by the user.

    A list of thesis objects, as defined in the thesis method. Use a subfield selector to access specific thesis fields.

    Note, that some theses may be hidden, in accordance to user preferences. Only authors, supervisors and reviewers can see all the theses.

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

services/theses/users

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

Get theses-related information on multiple users. This is very similar to the user method, but work with multiple users.
user_ids required

Pipe-separated list of user IDs.
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 of user 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 user_ids will be mapped to dictionary's keys, and each value will contain an object with user-related thesis data, as defined in the user method.

For invalid user_ids (users which do not exist) null will be returned (instead of a dictionary).
USOS API ver. 7.1.0.0-4, 0e1fe7fc, dirty (2024-08-27)