Rich Objects API

Rich objects are the primary feature of HyperCities. These contain not just objects that can be placed on a map, but a particular configuration of the geobrowser such as camera angle. All rich objects include rich HTML descriptions. Rich objects can include other objects to display along side them (even full collections), plus other historical maps, and can also set the particular view of the geobrowser, among other things. Some of these features are specific to Google Maps and Earth; it is up to the implementer how to implement these, if at all.

Please note: if a rich object contains other rich objects that also have view data, then the view data of the “main” rich object (the object that includes all the other objects) is what should be used. Also, if a rich object includes other rich objects that themselves have other rich objects (an odd situation, admittedly), only the main object and its immediate children should be displayed (at least, this is the prescribed behavior in the main HC viewer). No other attributes of the child objects should be displayed, such as historical maps, or the like.

Rich objects can belong to one or more collections, as well as to rich objects.

Objects and collections have both a “creator” and an “ownerId” field. The ownerId is a numeric foreign key to the users table, while the creator is a text field filled in at the time of creation. A user can attribute a project to a group, like “Pilipino Workers’ Center.” The same is true for collections.

JSON Representation of a Rich Object

{
   "creator": "admin", // Creator's name; assigned during object editing
   "owner": 17, // owner's numeric ID
   "bookmarks": [], // Any number of bookmarkers for Geoscribe
   "id": 24169, // object's ID in database
   "objectType": 6, // Object's type
   "copyright": "CCBY", // License under which content is protected
   "markerTypeId": 0, 
   "content": 12132, // ID number of the object’s content in the database; may be null
   "maps": [], // the entire JSON description of every map associated with this object
   "state": "2", 
   "mapType": "EARTH", // Map to use as basemap; no longer relevant in Earth-only HC
   "markerType": null, 
   "linkUrl": "http://linuxdev.ats.ucla.edu/provider/objects/24169", 
   "buildings": null, // Whether 3D buildings are enabled
   "description": null, 
   "mapping": {
       "swLat": "36.65504670", 
       "dateTo": {
           "date": "0525-01-01 00:00:00", 
           "timezone_type": 3, 
           "timezone": "America/Los_Angeles"
       }, 
       // either a link to the KML file of a 3D model, or a string of 
       // KML for any other kind of object
       "kml": "http://schnauzer.ats.ucla.edu/inscriptions/wp-content/uploads/2010/10/LateAntiqueForum.kml", 
       "dateFrom": {
           "date": "0404-12-31 00:00:00", 
           "timezone_type": 3, 
           "timezone": "America/Los_Angeles"
       }, 
       "zoom": "16", // default zoom level in Google Maps
       "neLon": "19.27059636",  // These four coordinates contain
       "neLat": "45.78679485",  // the object's minimum bounding rectangle.
       "swLon": "7.99368023", 
       "markerStyle": 0, // what kind of marker will be displayed; 0 means no marker
       // KML used to position camera in Google Earth
       "view": "<Camera><longitude>12.483669140652</longitude><latitude>41.892244214771</latitude><altitude>2165.514124593</altitude><roll>0</roll><tilt>0</tilt><heading>-0.76050292974789</heading></Camera>"
   }, 
   "coauthors": [
       "17" // ids of any users with editing privileges on the object
   ], 
   "objects": [], // the entire JSON description of every rich object 
                  // associated with this object, except for any of those 
                  // object’s child objects 
   "name": "Late Antique Forum 3D Models", 
   "stateId": "2", 
   "bubble": [{ // JSON objects that show any objects whose info 
                // bubbles should be opened when the object is loaded. 
                // This may also be an empty array.
      "id" : 1292, // Object id whose info bubble is showing
      "state" : "max" // or "min"; shows state of bubble
   }], 
   "isEarthObject": 0, 
   "ownerId": 17 // owner’s numeric ID
}

Response codes

A GET request to /objects or /objects/{id} will return one of the following responses:

HTTP Code	Data
200	JSON containing matching objects
404	ItemNotFound Exception

Editing and Updating Rich Objects

To edit or update a rich object, supply the following parameters:

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
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)	"private" only allows the owner to view and add to the collection.
objects	comma-separated list of IDs	Objects and collections that will be displayed on the map when viewing the object.
baseMap	JSON object, with one element, “baseMap”, which is an array of JSON objects. See "base maps" below.	Maps to be displayed when viewing the object. This allows both for maps stored in the HyperCities database, and also ArcGIS and WMS map services.
mapType	one of the following: “EARTH”, “BLANK”, “SATTELITE”, or “TERRAIN”	Which Google Map to use as the base layer. This is client-dependent; the default HyperCities client no longer supports this parameter because it users the Google Earth Plugin exclusively.
bubble	JSON string (optional), with following elements: {“id” : (object id whose info bubble is in), “state” : (“max” or “min”) }	What state the Google Maps or Google Earth bubble is in.
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.
markerState	integer	0 if the object’s marker should not appear on the map; 1 if it should
markerStyle	integer	1: point, 2: line, 3: polygon, 4: 3d point, 5: 3d line, 6: 3d polygon, 7: 3d model
latlng	JSON object with “latlng” member, which is array of objects with lat, lng, and alt elements	The data that actually appears on the map. These points represent the object’s position: one for a point, and any number for a line or polygon. The mapping field in the output is calculated from these.
dateFrom	ATOM-formatted date-time string (YYYY-MM-DDTHH:mm:SS)	the earliest date at which the object should appear on the map
dateTo	ATOM-formatted date-time string (YYYY-MM-DDTHH:mm:SS)	the latest date at which the object should appear on the map
zoom	integer	Zoom level at which to view the object in Google Maps.
view	JSON object with lat, lng, alt, and zoom elements	Describes the position of the viewport for the object.

Specifying Base Maps

Base maps should be supplied as JSON objects with the following form:

{ 
   "id": map ID, 
   "tileUrl": (optional if id is specified), 
   "layers": optional comma-separated list of layer IDs to show from maps that have multiple layers, 
   "opacity" : transparency setting for maps, where 1.0 is completely opaque and 0 is completely transparent, 
   "mapData" : JSON object of additional information to be sent to the map service, 
   "z-index": number indicating order of maps where lower ones are on the bottom, 
   "tileType": "ArcGIS", "WMS", or "0" for Google Maps-style maps, including those in HC. 
}

Marker States

A Rich Object may have the following states:

State ID	Description 0 if the object’s marker should not appear on the map; 1 if it should markerStyle integer 1: point 2: line 3: polygon 4: 3d point 5: 3d line 6: 3d polygon 7: 3d model