Layar Developer Documentation

Back to layar.com

Geolocation layer

Feature Introduction

A general use case of Layar is to show augments associated with physical geo-locations, such as restaurants, museums, ATM machines, festivals, etc. The GPS on the Layar Client can detect user's current location. Based on these information, a layer can be configured to return augments (or Point of Interests, POI) that are within certain search range around the user location.  

Key Steps to Implement

It is fairly easy to create a simple geo-location layer. Here we explain the key steps to create a simple layer.

Register a layer on the Publishing site

Once you have created a developer layar account, you can register a layer on the publishing site

If you are new to Layar, this is enough and you do not need to dive into figuring out the other parameters revealed by the "Edit" button yet.  

GetPOIs Response

In the GetPOIs response, each POI should have an anchor object defined. In this anchor object, developer needs to specify the latitude and longitude of this POI. Also, the altitude can be defined if applicable. 

anchor object_Geo-location POI
KeyTypeExampleExplanation
anchor json dictionary
"anchor": { 
 "lat": 52.373819, 
 "lon":4.932345, 
 "alt":100 }
The geo location coordinates of a POI, alt is optional but lat and lon are mandatory.

General Interaction Flow

The key components to enable a simple geo-location layer are:

Example Response

One sample getPOIs request:

http://devAPI.example.com/getPOIs/?countryCode=IN&lon=4.887339&userId=ed48067cda8e1b985dbb8ff3653a2da4fd490a37&radius=6245&lat=52.377544&layerName=snowy4&accuracy=100

In this getPOIs request, we will get the layer name, user's current location and the search range (radius) around the user. In the POI service provider, we need to calculate the distance between POIs and the user and only return POIs that are within the search range. An example of the getPOIs response looks like this:

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

Tutorial & Sample Code

You can find a step by step tutorial on how to create a simple Geo-location layer. Sample Code written in php is available for downloading at the end of the tutorial.

Notes

How to display geo-location POIs on a certain latitude ?

By default, all geo-location POIs will be placed at the same height of the user. In Layar Reality browser, this means right on top of the grid level. It is also possible to position a geo-location POI at a certain latitude.

The following parameters can be used to achieve this: 

APIParameterDescription
getPOIs requestaltThe current altitude of the user in meters. This is not always known on the client and will only be passed when there is a gps fix.
getPOIs responsealtReal altitude of object in meters. If this is missing, the same altitude as the user is assumed. NOTE: This parameter will be used only when the "alt" of the user is known to the device and passed through in the getPOIs request. Otherwise, the value will be ignored. You are strongly recommended to ONLY set "alt" in the JSON response, when an "alt" parameter is passed through the getPOIs request (GPS fix).
getPOIs responsetransform.translate.zThis parameter is always used and applied to POI's altitude. If you want to place a POI always relative to user's latitude, do not provide "alt" in the getPOI response and just specify this "transform.translate.z" parameter.

If you want to position a geo-location POI at its real altitude, you need to specify the "alt" parameter in "hotspots.anchor.geolocation" object. However this value will only be used when there is a GPS fix detected on the layer client which means an "alt" parameter is passed in the getPOIs request.  

If you want to position a geo-location POI at a altitude relative to user's height, please make used of "transform.translate.z". 

Please NOTE that we will not support using "alt" and "relativeAlt" at the same time in Layar v6.0 anymore. if your old layers use a combination of "alt" and "relativeAlt", please check your code to only return "alt" in the JSON response when "alt" is passed through the getPOIs request.

The maximum number of returned POIs

At present, we load a maximum of 50 POIs per call, including both Geo POIs and Vision enabled POIs.  At this time, we will not differentiate between the two in counts. We continuously work to improve that number and must account that not all phones are equal. For performance reasons, we cannot increase this number yet, however, as we improve performance and processing of target objects, we will look into increasing the number. If the developer formats their response to include one augment per target object and does not include GeoPOIs, they can have the maximum 50 target objects.  In summary, the limit applies to number of augments and is dictated by performance.

There are actually 2 maximums we need to consider:

So for example:

Once POIs are returned in the JSON response, for Geo POIs, please NOTE that the client will only display the POIs returned that fall within the range specified by the user with the range slider (or, if that slider is absent, within 1500m of the user). The distance between the user and the POIs is calculated using APIs provided by the OS of the client. Currently, on Android this is using the WGS 84 ellipsoid, which might lead to slightly different results than the Haversine Formula (which uses a perfect sphere). The difference is negligible in Layar, due to the small ranges normally used.