Layar Developer Documentation

◀ Back to layar.com

GetPOIs Response v6.0

Please NOTE that this documentation describes the getPOIs API v6.0. Developers must use this specification to create new geolocation layers. The API v6.0 is backward compatible with previous versions of the Layar Reality Browser (v3.0 and higher on Android, iPhone, Symbian and Blackberry). Layar Vision enabled layers are only supported on Layar v6.0 for Android and iPhone.

root.layer root.hotspots root.errorcode root.errorstring root.nextpagekey root.morepages root.radius root.refreshinterval root.refreshdistance root.fullrefresh root.actions root.showmessage root.deletedHotspots root.animations root.showDialog root.showDialog.title root.showDialog.description root.showDialog.iconURL root.showDialog.actions root.biwStyle root.disableClueMenu

Root JSON Response

layer string The name of the layer for which the POI's are returned.
Mandatory/Optional: mandatory
Path: root
Detailed Description: The unique layer name registered on the publishing site. It is used by layar server to identify POI service provider. It is passed through in the getPOIs request sent by the Layar client.
Example: 
"layer" : "hevie"
hotspots array of POI object The list of POIs for the current location and layer.
Mandatory/Optional: mandatory
Path: root
Detailed Description: An array of returned POI objects in response to a getPOIs request. Each POI object may contain various parameters. If no POI is returned, it should be an empty array. For detailed description, please .
Example: 
"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",
 }]
errorCode integer If an error condition occurs, this will be notified using the error code.
Mandatory/Optional: mandatory
Path: root
Detailed Description: The error codes that can be used by developers are 0 and 20-30. NOTE that in this case, the server is actually responding, this is different than a HTTP 500 Error situation (server error).
0 = "ok". No error, data available in the other fields.
20-29, can be used to send back an message.The string of the error will be displayed as a message in the screen of the user. NOTE that this will only be displayed if this is the first page in the response, errors sent in any successive page will be ignored.
30, can be used to indicate that this layer requires authentication. When this error code is returned in getPOI response, the client should open the webview at the 'URL for layer settings page' defined by the layer.
Example: 
"errorCode" : 0
errorString string The error message associated with the error code above.
Mandatory/Optional: mandatory
Path: root
Detailed Description: For each error code, developers can return custom messages which will be shown to the user in the AR view. This message can help improve user experience especially when something went wrong or you expect users to perform other actions. For instance when you expect users to change filter settings in order to see more POIs. NOTE that the maximum length is 80 Characters.
Example: 
"errorStrng" : "No POI found. Please increase the search range to try again."
nextPageKey string The key to the page being returned.
Mandatory/Optional: optional
Default value: null
Path: root
Detailed Description: The key to the page being returned in the following getPOIs request. Pass this key to the page parameter in the request if the next page is requested.
Example: 
"nextPageKey" : "aldsfj9348dk"
morePages boolean indicates whether more pages need to be retrieved.
Mandatory/Optional: optional
Default value: false
Path: root
Detailed Description: This parameter can be used to tell the service provider whether more pages need to be retrieved.
Example: 
"morePages" : true
radius integer Specifies the search radius when no radius value is present in the getPOIs request.
Mandatory/Optional: optional
Default value: null
Path: root
Detailed Description: Instead of providing a fixed search range, developers can also return a radius value in the response to assure that certain POIs are presented to the user. This can be done by emptying the default value of the search range filter on the publishing site. NOTE that this parameter must be returned if the GetPOIs request doesn't contain a requested radius. It cannot be used to overrule a value of radius if that was provided in the request. the unit is meter.
Example: 
"radius" : 1000
refreshInterval integer Indicates how many seconds to wait until the next getPOIs request is made.
Mandatory/Optional: optional
Default value: 300
Path: root
Detailed Description: This tells the layar client how many seconds to wait until the next getPOIs request is made. By default, it is 300s. The minimum value is 10s.
Example: 
"refreshInterval": 100
refreshDistance integer Indicates the distance threshold until the next getPOIs request is made.
Mandatory/Optional: optional for geo / deprecated for vision
Default value: 100
Path: root
Detailed Description: This tells the layar client to generate a new getPOIs request if the user has moved by more than the specified distance (in meters). By default, it is 100m. The minimum value is 3m.
Example: 
"refreshDistance": 50
fullRefresh boolean Indicates the type of refresh
Mandatory/Optional: optional
Default value: true
Path: root
Detailed Description: This tells the client the type of refresh that should be done:
true: the entire layer is refreshed, new POIs received will replace the current POIs.
false: the getPOIs response will just update the current POIs, so POIs returned are added (unknown id) or replacing (existing id) POIs.
Example: 
"fullRefresh": false
actions array of action objects Defines actions on entire layer level.
Mandatory/Optional: optional
Default value: empty array, []
Path: root
Detailed Description: This enables actions on the entire layer level. On layar client, an extra "Layer Actions" button will be shown if actions are defined. The action format is the same as for POI actions, except that POI-specific parameters will be ignored: closeBiw, autoTriggerRange and autoTriggerOnly. See details on the page.
Example: 
"actions": [{ 
  "contentType":"text/plain",  
  "method":"GET",    
  "uri":"http://mylayer.com/account/?online=true&",  
  "params": ["lat","lon"],  
  "label":"Go online",  
  "activityType":3}]
showMessage string A pop-up message as a result of a getPOIs request.
Mandatory/Optional: optional
Default value: null
Path: root
Detailed Description: This message is briefly displayed as pop-up on top of the current view, as a result of a getPOI request. Developers can use this message to provide users more instructions and feedback. This will help improve the user experience.
Example: 
"showMessage": "Congratulations! You just opened the treasure trove!"
deletedHotspots array of strings Specifies which POIs should be removed from the view.
Mandatory/Optional: optional
Default value: empty array, []
Path: root
Detailed Description: This is used in the response of an update action for specifying which hotspots (identified by the hotspot id) should be deleted from the view.
Example: 
"deletedHotspots": ["spot01", "spot02"]
animations string or json dictionary Defines animations on layer level.
Mandatory/Optional: optional
Default value: null
Path: root
Detailed Description: The animations defined on layer level should be applied to all POIs. NOTE that POI level animations will override layer level animations. See details on the page.
Example: 
"animations": { 
  "onClick": [{
    "interpolation": "overshoot",
    "to": 2,
    "length": 2000,
    "from": 0,
    "delay": 1000,
    "repeat": false,
    "type": "scale",
    "axis": { "y": 1, "x": 1, "z": 1 },
    "persist": true
  }]
}
showDialog json dictionary User interaction dialog.
Mandatory/Optional: optional
Default value: null
Path: root
Detailed Description: A configurable dialog with a descriptive text and optionally buttons linking to actions. It will be shown as a popup.
Example: 
"showDialog": {
  "title":"Some title",
  "description": "Some description",
  "iconURL": "http://developer.com/mybadge.png",
  "actions": [{
    "contentType": "application\/vnd.layar.internal",
    "uri": "layar:\/\/layername\/?action=refresh",
    "label": "Refresh POIs"}]
}
titlestringTitle of the dialog box
Mandatory/Optional:mandatory
Path: root.showDialog
descriptionstringText of the dialog box
Mandatory/Optional:mandatory
Path: root.showDialog
iconURLstringIcon to show in the dialog box
Mandatory/Optional:optional
Path:root.showDialog
actionsarray of action objectsButtons with various actions.
Mandatory/Optional:optional
Path: root.showDialog
Detailed Description:The same actions defined on POI level. On Android, the physical "back" button will dismiss the dialog. There is a small cross icon on the top right corner of the dialog which can be used to close it on iPhone.
biwStyle strings Specifies the BW style in the Camera view on layer level.
Mandatory/Optional: optional in geo / deprecated in vision
Default value: null
Path: root
Detailed Description: This forces the BIW style for all POIs to a certain form (verbose "classic" or lean "collapsed"). Set to null or do not send for default behavior, which is "classic" for geolocated POIs and "collapsed" for Vision POIs. NOTE that this key can also be specified at POI level. if both are present, the value defined for a POI overrules the one defined at the root level of the getPOIs response.
Example: 
"biwStyle": "collapsed"
disableClueMenu boolean Disables the clue menu for Vision enabled layer.
Mandatory/Optional: deprecated
Default value: false
Path: root
Detailed Description: For Vision enabled layer, this can be used to disable the menu that shows thumbnails of trackable images.
Example: 
"disableClueMenu": true

Complete JSON Response Example

{"hotspots": [], 
 "layer": "snowy4",
 "errorString": "No POIs are returned. Please adjust the filter settings.", 
 "errorCode": 20
}
{"hotspots": [{
   "id": "test_1",
   "anchor": { "referenceImage": "my_reference_image" },  
   "text": {
     "title": "The Layar Office", 
     "description": "The Location of the Layar Office", 
     "footnote": "Powered by Layar" },
 "imageURL": "http:\/\/custom.layar.nl\/layarimage.jpeg",
 }], 
 "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",
 }], 
 "layer": "snowy4",
 "errorString": "ok", 
 "errorCode": 0
}