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

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

Methods

faculties Get information on mulitple faculties.
faculty Get information on a given faculty.
search Search among faculties.
subfaculties_deep Get all descendant faculty IDs.

services/fac/faculties

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 mulitple faculties.
fac_ids required Pipe-separated list of faculty IDs.
fields required 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
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 faculty.
fac_id required ID of the faculty. If it doesn't exist, you will get a HTTP 400 error.
fields required 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),
  • postal_address - string; short, plain-text postal address of the faculty or null if address is unknown,
  • 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).

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.

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
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 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. 6.1.2.0-bc1aa53 (2016-06-07)