Collections API

Collections are ordered sequences of objects, and other collections (nested to any level). Accessing a collection will return a full description of all the objects inside them, which can be quite large.

This is the JSON description of an object. Many fields, as you will see, are shared between objects and collections.

{
   "description": "", // Full text description of the object
   "copyright": "CCBY", 
   "creator": "admin", 
   "name": "The Imperial Procession of 404 CE", 
   "mapping": {
       "swLat": "36.65504670", 
       "dateTo": {
           "date": "0525-01-01 00:00:00", 
           "timezone_type": 3, 
           "timezone": "America/Los_Angeles"
       }, 
       "kml": "", 
       "dateFrom": {
           "date": "0404-01-01 00:00:00", 
           "timezone_type": 3, 
           "timezone": "America/Los_Angeles"
       }, 
       "zoom": "14", 
       "neLon": "19.27059636", 
       "neLat": "45.78679485", 
       "swLon": "7.99368023", 
       "markerStyle": 0, 
       "view": "<Camera><longitude>12.486970755828</longitude><latitude>41.891783564551</latitude><altitude>60.785260345922</altitude><roll>3.4195511018927E-9</roll><tilt>81.922735124754</tilt><heading>-64.503780514316</heading></Camera>"
   }, 
   "id": 23077, 
   "state": "2", 
   "owner": 98, 
   "objectType": 2, 
   "linkUrl": "http://linuxdev.ats.ucla.edu/~jay/devHC/trunk/provider/collections/23077", 
   "children": [], // Full JSON of all objects in the collection. See Rich Objects for an example.
   "hcPermalink": "http://linuxdev.ats.ucla.edu/~jay/devHC/trunk/spawnSession.php?authType=shibboleth&collection=23077"
}

Searching

Searching for Collections (/collections, GET)

To search for collections, send a GET request to /collections. All criteria for objects are valid; there is only one additional field, "ids", a comma-separated list of IDs to query. The ids parameter can be used to search a number of collections for objects within them at the same time. The primary use for this is to search inside multiple collections.

Almost every HyperCities collection proceeds from a hierarchy that begins at one of a few root collections (in the main HyperCities instance): Public Collections, Featured Collections, Class Collections, or a user’s My Collections. For its browsing interface, the main HyperCities viewer searches these four collections instead of just searching all collections.

Creating and Editing

Creating and updating collections requires submitting the following fields. Many of them are the same as for objects, but there are a few key differences:

• A collection’s mapping is automatically calculated based on the objects inside it. A collection’s bounds always reflects the minimum bounding rectangle containing all of its child objects on the map, and the minimum timespan that contains them in time. Therefore, mapping does not need to be supplied when updating collections.
• Collections have no API for changing the objects inside them. To change the placement of objects, use the Rich Objects API.

Name	Value Type	Description
title	String (Max 255 Characters)	Title of object
description	HTML-formatted Text	Description of object
creator	String (Max 255 Characters)	Display name of creator; leave blank to use creator's full name.
coauthors	comma-delimited list of owner IDs	users who will also have editing privileges on the objects
shareAll	0 or 1	for collections, indicates whether or not to share all objects in collections with coauthors
password	String	Optional password if you wish to password-protect the collection so as to allow other users with the password to edit it. (We do not use this feature on HC much.)
ownerId	integer (foreign key to users table)	ID of owner in database
copyright	Either 'cc by', 'cc by-sa', 'cc by-nd', 'cc by-nc-sa', or'cc by-nc-nd'	Specifies which Creative Commons License the content is protected under. For more information, see http://creativecommons.org/about/licenses/.
state	1 (Public), 2 (Protected), 3 (Private)	"public" allows all users to view and add to the collection. "protected" allows all users to view the collection, but only those with a password to add to it. "private" only allows the owner to view and add to the collection.
parentIds	comma-separated list of IDs	Collections this object will belong to. These must be resubmitted completely every time an object is updated.
collectionPasswords	JSON Object of collection ID-password key-value pairs	User’s guess of any passwords for password-protected collections specified above in parentIds.

Ordering

Setting the order of objects within a collection in HyperCities can be complicated, and has not been implemented as part of the API. Since an object can be stored in multiple collections, an object’s order is an attribute of its relationship to the collection, not an intrinsic attribute of the object. Therefore, adjusting the order of objects within a collection means adjusting all the objects within a collection. It is a separate call from the standard /objects or /collections calls.

To adjust the order of objects within a collection, you need to acquire the object’s order ID within a collection; this is the value in the “parents” attribute, while the key is the parent collection ID. When you update an object’s position in the collection, order, you submit this order ID as well as the object’s new position in the collection. By implication, you need to send the order ID and new ordering of each object within the collection if it has changed in one request. This request is a POST request to updateOrder.php, and should have two parameters: an array of orderIDs called orderId, and an array of new orders called order. This will update the order for the entire collection.