Layar Developer Documentation

◀ Back to layar.com

hotspots

Please NOTE that this documentation describes the getPOIs API v6.2. Developers must use this specification to create new Vision layers. The API v6.2 is backward compatible with previous versions of the Layar Reality Browser (v3.0 and higher on Android and iPhone). AR videos will be supported in Layar client v6.2 (on Android and iPhone) soon.

root.hotspots.id root.hotspots.anchor root.hotspots.text root.hotspots.actions root.hotspots.imageURL root.hotspots.showSmallBiw root.hotspots.showBiwOnClick root.hotspots.biwStyle root.hotspots.icon root.hotspots.object hotspots.anchor.referenceImage root.hotspots.anchor.geolocation root.hotspots.anchor.geolocation.lat root.hotspots.anchor.geolocation.lon root.hotspots.anchor.geolocation.alt root.hotspots.text.title root.hotspots.text.description root.hotspots.text.footnote root.hotspots.icon.url root.hotspots.icon.type root.hotspots.object.contentType root.hotspots.object.url root.hotspots.object.size root.hotspots.object.reducedURL root.hotspots.object.previewImage root.hotspots.transform root.hotspots.transform.rotate root.hotspots.transform.rotate.rel root.hotspots.transform.rotate.axis root.hotspots.transform.rotate.angle root.hotspots.transform.rotate.axis.x root.hotspots.transform.rotate.axis.y root.hotspots.transform.rotate.axis.z root.hotspots.transform.translate root.hotspots.transform.scale root.hotspots.transform.translate.x root.hotspots.transform.translate.y root.hotspots.transform.translate.z root.hotspots.animations root.hotspots.inFocus Image Map

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"
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 actionspage.
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 a set of CIW (Custom POI Indicator Widget) icons 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 
}
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.
object json dictionary Uses a 2D (image), 3D (model) or AR video object to represent a POI.
Introduced API: v3.0; in v6.2 introduced "AR video" object for Vision layer.
Mandatory/Optional: optional for Geo layers ; mandatory for Vision layers
Path: root.hotspots
Detailed Description: In the Camera view, a POI can be represented by:
  • 2D image (introduced in API v3.0), file size should be smaller than 100Kb.
  • 3D model (introduced in API v3.0), file size should be smaller than 1Mb.
  • AR Video (introduced in API v6.2), videos need to be in MP4 container with h264 codec for video and AAC codec for audio. The resolution should be 320x240 pixels.
These objects will be rendered realistically as if they are placed in the real world. More detailed explanations on how to add objects to a layer and how layar clients render objects are documented here.
Example: 
"object": {
  "contentType": "model/vnd.layar.l3d",
  "url": "http://example.com/example_full.l3d",  
  "reducedURL": "http://example_reduced.l3d",  
  "size": 2
}
contentType string The content type of the object.
Mandatory/Optional: mandatory
Path: root.hotspots.object
Detailed Description: This determines whether a POI should be represented by a 2D image, a 3D model or an AR Video. The available options are:
  • image/vnd.layar.generic for any supported image type (PNG, GIF, JPEG);
  • image/jpeg, image/gif, image/png for images.
  • model/vnd.layar.l3d for 3D models.
  • video/mp4 for AR video.
url string The URL of the object to be displayed.
Mandatory/Optional: mandatory
Path: root.hotspots.object
size float The height of the object in meters.
Mandatory/Optional: mandatory
Path: root.hotspots.object
Detailed Description: This is used to specify the size of the object. For 2D images and AR videos, this determines the size at which the object will be rendered. For 3D models, this is a cue to the client whether to select the full model or the reduced model (if there is a reduced model) to download.
reducedURL string Geo Layer Only: the URL of a smaller version of object to be displayed.
Mandatory/Optional: optional for Geo layer / deprecated for Vision layer
Default value: null
Path: root.hotspots.object
Detailed Description: This defines a smaller version to be rendered when the POI is further away from the user. Specifying this can improve performance when there are many POIs on the screen. NOTE: Do not put the same URL here as for object.url, it will not have any functional effect and only consume bandwidth.
previewImage string Vision Layer Only: a placeholder of the AR video
Mandatory/Optional:
  • Not needed for 2d image and 3d model
  • mandatory for AR video
Path: root.hotspots.object
Detailed Description: This image is used while buffering the video. To make the AR video work across all platforms, developers can provide an image as the placeholder when no AR video playback is available on the device.
transform json dictionary Enhanced control of positioning objects.
Introduced API: v3.0; modified in API v6.0.
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 defaultMeans 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 "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 "hotspots.alt" 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.
Mandatory/Optional: optional
Default value: 1.0
Path: root.hotspots.transform
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

Complete JSON Response Example

{"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
} 

{"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 ResponseLayar Developer API - GetPOIs Response - actionsLayar Developer API - GetPOIs Response - animationsHowto - Geolocation layer explanationFirst Tutorial - Create a simple Geo-location layer