Accessing data on faculties and departments
:: services/fac module

These methods allow you to access information on faculties/deparatments, their structure, addresses etc.

Methods

factsheet_get Retrieve faculty's factsheet
faculties Get information on mulitple faculties.
faculty Get information on a given faculty.
resolve_facpattern Resolve facpattern value into a list of faculty IDs.
search Search among faculties.
subfaculties_deep Get all descendant faculty IDs.

services/fac/factsheet_get

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

Retrieve faculty's factsheet
fac_id required ID of the faculty
No additional OAuth arguments are required. If you provide any, they will be ignored.

Returned value:

Either a PDF file (with a valid Content-Type header), or a HTTP 4xx error response.

services/fac/faculties

Consumer: optional Token: optional Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/fac/faculties
Get information on mulitple faculties.
fac_ids required Pipe-separated list of faculty IDs.
fields optional

Default value: id|name

Pipe-separated list of fields you're interested in. This must be a subset of keys described in the faculty 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 with your fac_ids mapped to its keys. The value for a specific key depends whether it exists or not.

  • It it exists, the value will be of the same format as the one returned in the faculty method.
  • If it does not exist, the value will be null.

services/fac/faculty

Consumer: optional Token: optional Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/fac/faculty
Get information on a given faculty.
fac_id required ID of the faculty. If it doesn't exist, you will get a HTTP 400 error.
fields optional

Default value: id|name

Pipe-separated list of fields you're interested in. This must be a subset of keys 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 the fields you have supplied in your fields parameter. Available fields are:

  • id - the ID of faculty,
  • name - a LangDict object with the name of the faculty,
  • profile_url - faculty's USOSweb URL,
  • homepage_url - faculty's home page URL,
  • phone_numbers - a list of strings, each string represents one phone number of this faculty (in undocumented format),

  • phone_numbers2 - a list of objects, each object represents one phone number of this faculty.

    Currently available subfields:

    • comment - phone number comment (might be null),
    • number - string with phone number (in undocumented format),
    • type - type of phone number.
  • postal_address - string; short, plain-text postal address of the faculty or null if address is unknown,
  • email - string: faculty's email address.
  • is_public - boolean; indicates if this faculty should be shown to an "average user". There are many faculties which serve purely administrative purpose and are of no interest to most of the users. E.g. USOSweb displays only those faculties which are marked as public.

  • stats - various faculty statistics. You need to use a subfield selector to access these values!

    Important: These values are approximate and can be null. Null means that we cannot determine the value at the moment (or you don't have access to see it).

    • course_count - total number of courses organized by this faculty and its subfaculties,
    • programme_count - total number of programmes run by this faculty and its subfaculties,
    • staff_count - total number of staff members employed by this faculty and its subfaculties,
    • subfaculty_count - total number of subfaculties of this faculty, including all the descendant faculties (subfaculties of the subfaculties),
    • public_subfaculty_count - as above, but only public faculties will count (in most of the cases you probably should use this one, instead of the one above!).

  • path - a list of ancestor faculties, starting from the root, and not including this faculty. For root faculties, this list will be empty.

    Each item on this list is a faculty object, as returned by the faculty method. You must use the subfield selector to supply the list of fields which you require. You can use only a subset of faculty fields in this subfield selector: only id, name and profile_url are allowed.

  • static_map_urls - various maps of the surrounds of the faculty compound (with the faculty marked, if possible). Use the subfield selector to choose the map size(s).

    Currently available subfields:

    • 100x100 - 100px x 100px,
    • 200x200 - 200px x 200px,
    • 300x300 - 300px x 300px,
    • 400x200 - 400px x 200px,
    • 600x300 - 600px x 300px,
    • 800x400 - 800px x 400px,
    • 1000x250 - 1000px x 250px.

    Every one of these fields may contain null and you should be prepared for that (some faculties simply don't have any exact location).

    Even when it's not null, the URL is NOT guaranteed to be valid. For example, if our tile-map backend fails on us, then the URL will lead you to a HTTP 404 page. We will try to return null if we expect the URL to be invalid, but we do not guarantee this.

    The image which the URL points to, should be cached according to its Cache-Control and Expires headers. If you're displaying the image in a browser then you don't have to worry about the caching yourself (the browser will cache it for you).

  • logo_urls - the URLs of the logo of the faculty, in various dimensions, or a set URLs of placeholder images if this faculty does not have a logo. Use the subfield selector to choose the wanted size/dimensions of the logo.

    Currently available subfields:

    • 50x50 - 50px x 50px,
    • 100x100 - 100px x 100px,
    • 200x200 - 200px x 200px,

    • screen - full-screen version of the logo, the dimensions are undocumented and may vary on faculty and/or USOS API version (since screens are getting bigger in time).

      Note, that in some rare cases, this image can be actually smaller than the others. This happens when we don't have a high resolution logo of a faculty and the original has to be enlarged in order to fit into 200x200 dimensions, etc.

    The image which the URL points to, should be cached according to its Cache-Control and Expires headers. If you're displaying the image in a browser then you don't have to worry about the caching yourself (the browser will cache it for you).

  • cover_urls - the URLs of the cover of the faculty, in various dimensions, or a set of nulls if this faculty does not have a cover. Use the subfield selector to choose the wanted size/dimensions of the cover.

    Currently available subfields:

    • 400x200 - 400px x 200px,
    • 1000x250 - 1000px x 250px,
    • 1000x350 - 1000px x 350px,

    • screen - full-screen version of the cover; the exact dimensions are undocumented and may vary on faculty and/or USOS API version (since screens are getting bigger in time).

      Note, that in some rare cases, this image can be actually smaller than the others. This happens when we don't have a high resolution cover of a faculty and the original has to be enlarged in order to fit into 400x200 dimensions, etc.

    The image which the URL points to, should be cached according to its Cache-Control and Expires headers. If you're displaying the image in a browser then you don't have to worry about the caching yourself (the browser will cache it for you).

  • pdf_factsheet_url - string or null; If not null, then it will contain a publicly accessible URL of the faculty's PDF factsheet (a collection of information for incoming mobility students, and external IRO staff members).

services/fac/resolve_facpattern

Consumer: optional Token: optional Scopes: n/a SSL: required
https://usosapi.panschelm.edu.pl/services/fac/resolve_facpattern

This method allows the caller to "select" a set of faculties with help of a specially formatted string called a "facpattern".

Other USOS API methods may make use of this method whenever they want their users to use facpatterns. This method serves as the primary location for facpattern's documentation.

Facpattern is a string of pipe-separated "facpattern entries". Each of these entries consists of a single character prefix (described below), followed by a faculty ID (which MUST refer to an existing faculty). Depending on the prefix, different sets of faculties are added to the final result. Currently allowed prefixes are:

  • = - add the faculty (and only this faculty) to the result,
  • + - add the faculty and all its descendants to the result,
  • < - add the faculty and all its ancestors to the result.

For example, facpattern=<A12|+A70 will resolve to the following list: faculty A12, all ancestor faculties of faculty A12, A70, all descendant faculties of faculty A70.

Also note, that root faculty can be found via the institution field of the installation method. Using this ID with the "+" prefix will allow you to select all faculties.
facpattern required The pattern, as desribed in the method above.
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 faculty IDs which matched the given pattern.

If any of the facpattern entries refers to a non-existent faculty, USOS API will respond with a HTTP 400 error.
Consumer: optional Token: optional Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/fac/search

Search for faculties matching given query and conditions.

By default, this method will search among only such faculties which were marked as "publicly visible". See visibility parameter.
lang required Code of the preferred language. This usually should match the language of your user interface.
query required The query to search with. Part of faculty's name or code, etc.
fields optional

Default value: id|match

Pipe-separated list of fields. All fields described in the faculty method are allowed plus one more:

  • match - HTML string. It will include faculty's name, but it may also contain other data (such as faculty's code). Fragments that have matched your query will be highlighted with a <b> tag.
visibility optional

Default value: public

One of the following values:

  • public - search among only such faculties which were marked as "publicly visible",
  • all - search among all 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

Indicates the first matching search result that should be included in the response. 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 results 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.
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 the following structure:

  • items - a list of matching faculties. The length of this list is limited to num items. You can access more results by specifying the start parameter.

    Items on the list are dictionaries of selected fields.

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

services/fac/subfaculties_deep

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapi.panschelm.edu.pl/services/fac/subfaculties_deep
Get the list of all descendant faculty IDs of a given faculty.
fac_id required ID of the 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 list of strings - all descendant faculty IDs of the given faculty (the root faculty is not included).
USOS API ver. 7.1.0.0-4, 0e1fe7fc (2024-08-27)