Buildings, rooms and other geographical data
:: services/geo module

These methods allow you to access all kinds of USOS-related geographical data, like maps, locations of university buildings, etc.

Methods

building (deprecated) Get information on a given building
building2 Get information on a given building
building_index Get the list of all buildings.
buildings (deprecated) Get information on multiple buildings
buildings2 Get information on multiple buildings.
room Get information on a given room.
rooms Get information on multiple rooms.
staticmap BETA Get a map of the surroundings of a given point (administrative)

services/geo/building

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapps.demo.usos.edu.pl/services/geo/building

This method is deprecated, please avoid using it - read more

Suggested replacement: services/geo/building2

Get information on a given building. This method had multiple errors and has been deprecated. We advise not to use it.

building_id required ID of the building.
fields optional

Default value: id|name|location

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 - building ID;

  • name - the building's name, in Polish only.

    Deprecated. Use the building2 to get the name in a proper LangDict object.
  • location - this will be always null.

    This field had a major bug - latitude and longitude were switched places! We decided to fix this by returning null every time, which will make your app perceive the building as a building with no location. We think it's safer than continuing the previous behavior. Please use the building2 method to get the location of the building.

Thrown errors:

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

services/geo/building2

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapps.demo.usos.edu.pl/services/geo/building2

Get information on a given building

building_id required ID of the building.
langpref optional

Default value: en

A code of the preferred language ("pl" or "en"). It may influence the order of data and other display properties of the returned fields.
fields optional

Default value: id|name|location

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:

  • Primary:

    • id - building ID;

    • name - LangDict object with the building's name;

    • profile_url - building's USOSweb URL;

    • postal_address - string; short, plain-text postal address of the building, or null if the address is unknown;

    • campus_name - a LangDict object with the name of the building's campus, or null if the building is not part of any campus (or the data is missing).

      In general, campus name should be short (~20 characters), but some institutions don't follow that guideline (e.g. names contain lists of streets, etc.).

    • erp_id - Building's ERP id.

      This field has been replaced by hr_id field.
    • hr_id - Building's HR ID;

    • location - geographical location of the building or null if location is unknown.

      Location is presented in a form of a dictionary with two fields:

      • long - longitude, a floating point number, measured in degrees (east - positive),
      • lat - latitude, a floating point number, measured in degrees (north - positive).
    • marker_style - BETA suggested map marker style.

      Some institutions may suggest specific styles for the markers used on the map of their buildings. This object describes these suggestions.

      Currently, only one subfield is present - color. It contains a suggested color for the marker in a hexadecimal RGB format, e.g. #000000 for black.

    • phone_numbers - list of strings, each string represents one phone number specified for this building (in undocumented format).

      Note, that this field is dynamically calculated. We "guess" which phone numbers are best suited to be returned here (if there are too many, then we try to pick one or two we think best).

    • static_map_urls - Maps showing the building's location.

      A set of map images, showing the surroundings of the building (with the building marked in the center). 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 buildings don't have a 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).

    • photo_urls - URLs of the photo of building.

      The URLs of the photo of the building, in various dimensions, or a set URLs of placeholder images if this building does not have a photo. Use the subfield selector to choose the wanted size/dimensions of the building.

      Currently available subfields:

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

      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).

  • Secondary:

    • related_faculties - list of faculties related to this building.

      Each item on the list is a faculty object, as defined in the services/fac/faculty method. You can use the subfield selector to access specific faculty fields.

      If you supply name as one of the subfields, then the faculties on this list will be ordered by name (see also the langpref parameter). This behavior may change (e.g. we may decide to put more important faculties up front).

    • all_phone_numbers - List of all phone numbers associated with a building.

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

    • rooms - List of all rooms associated with a building.

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

Thrown errors:

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

services/geo/building_index

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapps.demo.usos.edu.pl/services/geo/building_index

Get the list of all buildings known to the institution.

fields optional

Default value: id|name|location

Selector of result fields you are interested in. The selector must contain subset of primary fields, which are described in the returns section of building2 method.

fac_ids optional

Default value: (empty string)

Pipe-separated list of faculty IDs. If given, then the result will contain only such buildings which are related to one of more of the given faculties.

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:

Unordered list of dictionaries. Each dictionary will contain a building description (as described in the building2 method) with the chosen fields.

services/geo/buildings

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapps.demo.usos.edu.pl/services/geo/buildings

This method is deprecated, please avoid using it - read more

Suggested replacement: services/geo/buildings2

Get information on multiple buildings.

This method is similar to the building method, and it was deprecated for the same reasons. Please use the buildings2 method instead.

building_ids required Pipe-separated list of building IDs.
fields optional

Default value: id|name|location

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

No additional OAuth arguments are required. If you provide any, they will be ignored.

Returned value:

A dictionary: your building_ids will be mapped to dictionary's keys, and each value will contain the description of a building, as defined in the building method.

services/geo/buildings2

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapps.demo.usos.edu.pl/services/geo/buildings2

Get information on multiple buildings.

This method is similar to the building2 method, but it can return multiple objects at one time.

building_ids required Pipe-separated list of building IDs.
langpref optional

Default value: en

As described in the building2 method.
fields optional

Default value: id|name|location

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

No additional OAuth arguments are required. If you provide any, they will be ignored.

Returned value:

A dictionary: your building_ids will be mapped to dictionary's keys, and each value will contain the description of a building, as defined in the building2 method.

services/geo/room

Consumer: optional Token: optional Scopes: n/a SSL: not required
https://usosapps.demo.usos.edu.pl/services/geo/room

Get information on a given room.

room_id required ID of the room.
fields optional

Default value: id|number|building_id|building_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.

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:

  • Primary:

    • id - room ID;

    • number - string, a room number (e.x. "104B");

    • building_id - ID of a parent building.

      This field is deprecated. You are advised to use the building field instead.
    • building_name - a LangDict object with the name of a parent building.

      This field is deprecated. You are advised to use the building field instead.
    • building - Building where the room is located.

      This field references objects returned by building2 method. See its returns section for possible subfields (only primary are allowed).

    • type - type of the room.

      Currently two values are possible:

      • D - didactics room,
      • P - staff member's office.
    • capacity - approximate number of people that would fit into the room or null if this number is unknown;

    • attributes - attributes of the room.

      A dictionary of the following structure:

      • id - ID of the attribute
      • description - langdict, description of the attribute
      • count - count of objects in the room described by the attribute or null if this number is unknown or does not apply.
  • Secondary:

    • staff - List of people assigned to this room.

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

      Additional permissions note: Consumer key is required.

Thrown errors:

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

services/geo/rooms

Consumer: optional Token: optional Scopes: n/a SSL: not required
https://usosapps.demo.usos.edu.pl/services/geo/rooms

Get information on multiple rooms.

This method is similar to the room method, but it works with multiple rooms.

room_ids required Pipe-separated list of room IDs.
fields optional

Default value: id|number|building_id|building_name

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section of room 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: your room_ids will be mapped to dictionary's keys, and each value will contain the description of a room, as defined in the room method.

services/geo/staticmap

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

Consumer: required (administrative) Token: ignored Scopes: n/a SSL: not required
https://usosapps.demo.usos.edu.pl/services/geo/staticmap

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 a static map image of the surroundings of a given point.

This method uses external OpenStreetMap tile servers. Please keep the following in mind:

  • You must comply with OSM's tile usage policy before you use this method as a proxy.
  • USOS API "signs" all requests with the URL of this USOS API installation (in the User-Agent header). Don't abuse the OSM project via USOS API - it may cause your USOS API installation to be blocked by OSM (based on either IP and/or User-Agent).
  • All downloaded tiles are cached. All static maps are generated with the cached tiles. There is no way for you to skip this behavior and "refresh" the cache. If you feel it's necessary to clear the cache, please contact USOS API administrators.
  • Currently, if something goes wrong with the tile download, we will also cache such response (we won't repeat the download). Even if the tile server was down only for only a couple of seconds, we will not query it again for some time. During this period, you will receive HTTP 404 response instead of your static map.
  • If this is read by anyone from OSM: If you feel there's any abuse, please contact us.

This method was not checked to work in edge cases. Keep your queries "rational".

lat required

Latitude of the image center.

long required

Longitude of the image center.

zoom optional

Default value: 15

Zoom level to use (0..18).

width optional

Default value: 200

The width of the result image, in pixels (1..800).

height optional

Default value: 200

The height of the result image, in pixels (1..800).

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:

  • HTTP 404 response, if some of the required tiles could not be fetched.
  • If successful, a HTTP 200 response with the image. Currently, the image is returned in JPEG format, but this may change without notice. You should be ready to handle other common formats, like PNG or GIF.
USOS API ver. 7.1.1.0-1, f733442d, dirty (2024-11-25)