Buildings, rooms and other geographical data

:: services/geo module

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.

Returned value:

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

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.

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.

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.

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.