Rich Objects API

(Difference between revisions)
Jump to: navigation, search
(Initial version of page.)
 
(Added information on editing Rich Objects.)
Line 7: Line 7:
 
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.
 
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 =
 
<code>
 
<code>
 
  {
 
  {
Line 67: Line 68:
  
  
−
 
+
= Response codes =
 
A GET request to /objects or /objects/{id} will return one of the following responses:
 
A GET request to /objects or /objects/{id} will return one of the following responses:
  
Line 80: Line 81:
 
|ItemNotFound Exception
 
|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)
 +
|"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.
 +
|-
 +
|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
 +
|See [[Marker States]]
 +
|-
 +
|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:
 +
<code>
 +
{
 +
    "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.
 +
}
 +
</code>

Revision as of 16:20, 5 June 2013

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.

Contents

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 See Marker States
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. 
}

Retrieved from "http://help.hypercities.com/index.php?title=Rich_Objects_API&oldid=682"
Personal tools
Namespaces
Variants
Actions
Navigation
Toolbox