Layar Developer Documentation

◀ Back to layar.com

hotspots

Please NOTE that this documentation describes the getPOIs API v8.3. The API v8.3 is backward compatible with previous versions of the Layar Reality Browser (v7.0 and higher on Android and iPhone).

id anchor text actions imageURL showSmallBiw showBiwOnClick biwStyle icon transform aniamtions inFocus handlers

JSON Response - hotspots object

id string The unique id for the POI
Introduced API: v2.1
Mandatory/Optional: mandatory
Path: root.hotspots
Detailed Description: The unique id which identifies a POI in the getPOIs response. This is used to track the POIs when refreshing the layer.
Example: 
"id" : "ae22826e16829a6f"
anchor Type: string or json dictionary Placement of the POI.
Introduced API: v6.0
Mandatory/Optional: mandatory
Path: root.hotspots
Detailed Description: Placement of the POI. Can either be a geolocation or the key of a reference image in Layar Vision. For geolocation, alt is optional but lat and lon are mandatory.
Example: 
"anchor": { "referenceImage": "myFirstImage" }
"anchor": { "geolocation": { "lat": 52.3, "lon": 4.5 } }
"anchor": "geo:52.3,4.5"
geolocation json dictionary The geo coordinates of a POI.
Path: root.hotspots.anchor
Detailed Description: The geo location coordinates of a POI, alt is optional but lat and lon are mandatory.
Example: 
 "geolocation": { "lat": 52.3, "lon": 4.5, "alt": 20 }
lat decimal The decimal GPS coordinate value of the latitude for the POI.
lon decimal The decimal GPS coordinate value of the longitude for the POI.
alt decimal The decimal GPS coordinate value of the altitude for the POI.
referenceImage string the key of a reference image.
Path: root.hotspots.anchor
Detailed Description: The image key of the reference image uploaded to the publishing site.
Example: 
"referenceImage": "myFirstImage"
geolocation string The geo coordinates of a User.
Introduced API: v8.3
Path: root.hotspots.anchor
Fixed Value: user
Detailed Description:  This is mostly used when POIs are tied to user's location (experience domes)
Example: 
 "geolocation":  "user"
poi string The id of a POI.
Introduced API: v8.3
Path: root.hotspots.anchor
Detailed Description:  Support of POI anchors was introduced in 8.3 Users can attach one poi on another one by defining it's id as POI value.
Example: 
 "anchor": { "poi": my_poi_id }
text json dictionary Geo Layer Only: Descriptive text about the POI displayed in the BIW.
Introduced API: v6.0
Mandatory/Optional: mandatory for Geo layer/deprecated for Vision layer
Path: root.hotspots
Detailed Description: For Geo layers, each POI has a brief information widget (BIW) which can be used to provide some text to describe the POI (no HTML is supported). It contains three parameters, title, description and footnote. The structure of the "text" object looks like follows:
Example: 
"text": {
  "title": "Layar office",
  "description": "The location of the Layar HQ in Amsterdam",
  "footnote": "Powered by Layar" 
}
title string The title of the POI
Mandatory/Optional: mandatory
Path: root.hotspots.text
Detailed Description: This is the first line in the BIW dialog on the client. It has larger font and uses the Banner text color defined under the "Look & feel" tab of the publishing site. The recommended maximum string length is 60 characters and it will be wrapped over 2 lines.
description string the main content of the BIW.
Mandatory/Optional: optional
Default value: null
Path: root.hotspots.text
Detailed Description: Some text can be used to explain the POI. It has normal font and uses the BIW Text Color defined under the "Look & feel" tab of the publishing site. The recommended maximum string length is 140 characters and it will be wrapped over 3 lines.
footnote string The last line in the BIW.
Mandatory/Optional: optional
Default value: null
Path: root.hotspots.text
Detailed Description: One line of string at the bottom part of the BIW. It has small font and uses the BIW Title Color defined under "Look & feel" tab of the publishing site. The recommended maximum string length is 45 characters without wrapping. Extra characters will be cut off on the screen.
actions array of action objects Defines actions on POI level.
Introduced API: v2.1; modified in later API versions.
Mandatory/Optional: optional
Default value: empty array, []
Path: root.hotspots
Detailed Description: This enables actions on the POI level. Each POI can have its own actions. They will appear on the expanded BIW dialog. See details on the actions page.
Example: 
"actions": [{ 
  "contentType":"text/plain",  
  "method":"GET",    
  "uri":"http://mylayer.com/account/?online=true&",  
  "params": ["lat","lon"],  
  "label":"Go online",  
  "activityType":3}]
imageURL string Geo Layer Only: an image displayed in the BIW of a POI.
Introduced API: v2.1
Mandatory/Optional: optional for Geo layer/deprecated for Vision layer
Default value: null
Path: root.hotspots
Detailed Description: The location of the image to be displayed inside the BIW. If the image is too large, it will be resized to fit within a bounding box of 100x75 pixels, preserving aspect ratio. NOTE: the image file size should be smaller than 100kb, otherwise, the image will not be loaded.
Example: 
"imageURL" : "http:\/\/94.100.16.70\/1790001\/2346232\/1344536_5_7u7.jpeg"
showSmallBiw boolean Geo Layer Only: decides whether a small BIW dialog should be shown
Introduced API: v4.0
Mandatory/Optional: optional for Geo layer / deprecated for Vision layer
Default value: true
Path: root.hotspots
Detailed Description: This tells the layar client whether or not a small BIW (the one at the bottom of the screen) should be shown when the POI is in focus.
Example: 
"showSmallBiw" : false
showBiwOnClick boolean Geo Layer Only: decides whether a detailed BIW dialog together with actions list should be shown
Introduced API: v4.0
Mandatory/Optional: optional for Geo layer / deprecated for Vision layer
Default value: true
Path: root.hotspots
Detailed Description: This tells the client whether or not a detailed BIW (the big one in the middle of the screen) should be shown when the user clicks on the POI or on the small BIW. If the value is false, the first action from the list of actions will be fired instead. NOTE: This means there is no way for the user to manually access the actions. The first one is triggered by a user click, one other action can be activated by using autoTrigger settings. More than 2 actions won't be used.
Example: 
"showBiwOnClick": false
biwStyle string Geo Layer Only: specifies the BIW display style.
Introduced API: v6.0
Mandatory/Optional: optional for Geo layer / deprecated for Vision layer
Default value: "classic"
Path: root.hotspots
Detailed Description: This tells the client which BIW style should be used, classic or collapsed. "classic" style displays the entire "text" object when a POI is in focus while "collapsed" style only shows the text.title parameter. This POI level "biwStyle" will overrule the "biwStyle" defined on the layer level.
Example: 
"biwStyle": "collapsed"
icon json dictionary Geo Layer Only: defines the CIW icon representation for a POI in the Camera view.
Introduced API: v6.0
Mandatory/Optional: optional for Geo layer/ deprecated for Vision layer
Path: root.hotspots
Detailed Description: A POI can be represented by an icon defined in the "url" parameter below or the POI icon sets defined on the publishing site. If a few POIs serve the same kind of purpose and can be represented by the same icon set, it is recommended to use the CIW icon sets. You can check here to learn more on how Layar client renders POIs in the Camera view.
Example: 
"icon": {
  "url": "http://example.com/icon.png",
  "type": 2  // this value corresponds to the POI icon set defined in the publishing environment
}
url string The URL to the icon image
Mandatory/Optional: optional
Default value: null
Path: root.hotspots.icon
Detailed Description: Each POI can be represented by an image defined in this url
type integer The type of CIW set
Mandatory/Optional: optional
Default value: 0
Path: root.hotspots.icon
Detailed Description: On the publishing site, CIW icon set can be defined under the "Look & feel" tab. Each CIW icon set will have a type value. In the JSON response, you can fill in the right type value to determine which CIW icon set should be used to represent a POI.
transform json dictionary Enhanced control of positioning objects.
Introduced API: v3.0; modified in API v6.0 and 8.3
Mandatory/Optional: optional
Path: root.hotspots
Detailed Description: A few factors can be used to transform objects in Camera view, for instance scale, rotation and translate.
Example: 
"transform":  {
  "rotate": {  
     "rel": true,    
     "axis": { "x": 0, "y": 0, "z": 1 },
     "angle": 0   
  },  
  "translate": { "x": 0, "y": -0.075, "z": 0 },  
  "scale": 0.01
}
rotate json dictionary Rotates object over the given axis in its own local coordinate system.
Mandatory/Optional: optional
Path: root.hotspots.transform
Example: 
"rotate": {  
  "rel": true,    
  "axis": { "x": 0, "y": 0, "z": 1 },
  "angle": 0   
}
rel boolean, optional, false by default Means the rotation is relative to the user around z-axis. On layar client, "axis" and "angle" are applied after "rel" has been applied. If "rel" is set to true, the Geo-location or Vision enabled POI will rotate over the Z-axis to face the user first, then it will rotate around the defined "axis" with a certain degrees defined in "angle" parameter. From then on, the rotation is relative to the user around z-axis.
axis json dictionary mandatoryEach axis has a type of float.
angle decimal mandatoryRotation angle in degrees to rotate the object around the z-axis. The rotation direction is determined by the usual right-hand thumb rule (positive angle: counter clock-wise in the x-y plane).
translate json dictionary Translate the POI to another location from its anchor point.
Mandatory/Optional: optional. If used, all the axes are mandatory and the type should be decimal.
Path: root.hotspots.transform
Detailed Description: This can be used to position the object at another location within the coordinate system. The distance unit is meter. NOTE that "transform.translate.z" parameter is applied to object's altitude. If you want to place a POI always relative to user's latitude (object's initial anchor point), do not provide "alt" in anchor dictionary in the getPOI response and just specify this "transform.translate.z" parameter.
Example: 
"translate": { 
  "x": 0, 
  "y": -0.075, 
  "z": 0 
}
scale decimal The multiplication factor to scale the object. (Uniform)
Mandatory/Optional: optional.
Default value: 1.0
Path: root.hotspots.scale
Example: 
"scale": { 2.0}
scale json dictionary The multiplication factor to scale the object. (Non Uniform)
Mandatory/Optional: optional.If used, all the axes are mandatory and the type should be decimal.
Default value: 1.0
Path: root.hotspots.scale
Example: 
"scale": { 
  "x": 1.0, 
  "y": 1.0, 
  "z": 1.0 
}
animations string or json dictionary Animations can be applied to a POI.
Mandatory/Optional: Optional
Default value: null
Path: root.hotspots
Detailed Description: This defines the animation for this specific POI. If defined, it overrides the default animations definition on layer root level. Please read here for detailed specification.
Example: 
"animations": {
  "onClick": [ 
    {
      "interpolation": "overshoot",
      "to": 2,
      "length": 2000,
      "from": 0,
      "delay": 0,
      "repeat": false,
      "type": "scale",
      "axis": {  "y": 1, "x": 1, "z": 1 },
      "persist": true
   }]
}
inFocus boolean Geo Layer Only: specifies whether a POI should be locked initially in the AR view.
Mandatory/Optional: optional for Geo layer/ deprecated for Vision layer
Default value: false
Path: root.hotspots
Detailed Description: A value of True indicates to the client that this particular POI should be locked directly when the POIs are shown. Only one POI can have this flag set to true in the getPOIs response. If more than one POI has this value set to True, the client will pick one (no guarantee which). By default, it is false.
Example: 
"inFocus": true
handlers stringAllows for actions or POI updates to be triggered at certain events.
Mandatory/Optional: optional the event handler should be defined
Default value: false
Path: root.handlers
Detailed Description: Contains the reaction of the handler. Enables developers to add more complex functionality to their experiences, e.g. sequencing of videos, but also dynamic content without server interaction.
Example: 
"handlers": {	"doSomething":{
		 "update":{			"hotspots":[{...}]	
                                   }}
}

Complete JSON Response Example

  • When Vision POIs are returned
{"hotspots": [{
   "id": "test_1",
   "anchor": { "referenceImage": "my_reference_image",  
   "actions": [{
     "uri": "tel:215-862-1996",
     "autoTrigger": true,
     "autoTriggerOnly": true,
     "contentType": "application\/vnd.layar.internal",
     "method": "POST",
     "showActivity": false,
     "activityMessage": "calling layar"
    }], 
    "object": {
      "contentType": "model/vnd.layar.l3d",
      "url": "http://example.com/example_full.l3d",   
      "size": 2
    },
    "transform":  {
      "rotate": {  
      "rel": true,    
      "axis": { "x": 0, "y": 0, "z": 1 },
      "angle": 0   },  
      "translate": { "x": 0, "y": -0.075, "z": 0 },  
      "scale": 0.01
    } 
 }], 
 "layer": "snowy4",
 "errorString": "ok", 
 "errorCode": 0
}
  • When Geo-location POIs are returned
{"hotspots": [{
   "id": "test_1",
   "anchor": { "geolocation": { "lat": 52.3729, "lon": 4.93 } },  
   "text": {
     "title": "The Layar Office", 
     "description": "The Location of the Layar Office", 
     "footnote": "Powered by Layar" },
   "imageURL": "http:\/\/custom.layar.nl\/layarimage.jpeg",
   "actions": [{
     "label": "Contact Layar",
     "uri": "http:\/\/layar.com\/company\/contact\/",
     "autoTriggerRange": 5000,
     "autoTriggerOnly": true,
     "contentType": "text\/plain",
     "method": "GET",
     "activityType": 1,
     "params": [
       "lat",
       "lon"
     ],
     "closeBiw": false,
     "showActivity": true,
     "activityMessage": "contact layar"
    }]
 }], 
 "layer": "snowy4",
 "errorString": "ok", 
 "errorCode": 0
}

Related topics

Layar Developer API - GetPOIs Response Layar Developer API - GetPOIs Response - actions Layar Developer API - GetPOIs Response - animations Howto - Geolocation layer explanation First Tutorial - Create a simple Geo-location layer