Please NOTE that this documentation will not be updated anymore. Please see our new Developer Documentation Site for the latest updates!

This is the first of a series of tutorials on how to create a layer using the Layar developer API. Each tutorial will explain how to implement a specific feature within a layer. The idea is to help developers to get started with developing their own layers faster.

In this first tutorial, we explain how to create a simple layer step by step. Only the basic code for creating a layer is explained here. It will be used as the foundation for the coming tutorials. Other features like actions and 3D objects will be introduced in the near future.

Generally, the steps to create a layer can be outlined as follows:

Sign up to be a developer
Define and edit a layer on the publishing site
Prepare the database
Gather POIs information
Build a web service
Test the layer
Publish the layer

A layer can be written in various programming languages. In this tutorial however, we give the sample code in PHP. We make use of the following packages:

A web server with PHP (5.2 or above) which supports JSON
A MySQL database (preferably with phpMyAdmin)

When the needed applications are installed, we follow the steps mentioned above to create a simple layer.

1. Sign up to be a developer

Before creating a layer, a developer needs to sign up to be a developer on layar website. For more information on how to become a layer developer, please read Sign up to be a developer. After activating the account, the developer can sign in on the publishing site.

2. Define and edit a layer on the publishing site

After logging in, the developer can define a new layer by clicking the "Create a Layer" button under "layers" section on the publishing site. In this tutorial, we create a layer which shows the location of the Layar office in Amsterdam as an example (see sreenshot below). More details of defining a layer can be found at the Create a layer page.

screenshot 1 - "create a layer" button

screenshot 2 - create a layer form

Each field in the above screenshot is explained below. More information can be obtained from Create a layer .

Fields	Description	Example value (Please customize this)
Layer name	A unique name for your layer	layaroffice
Title	The title that will be visible once it is published	The Layar Office
Publisher name	The name of the publisher	Layar
Layer type	The type of the layer, can also be 3D and 2D objects in 3D space (will be introduced in later tutorials)	Generic (2D)
API endpoint URL	The URL for the web service that provides information about points of interest (POIs) in the database.	http://custom.layar.nl/FirstTutorial.php
Short Description	A short description of the layer and where the POIs are located	This layer shows the location of the Layar office in Amsterdam

After completing the form, click "Create layer" button and the layer appears in the layer list.

screenshot 3 - created layer in the list

Click on "Edit" button to further customize this layer.

screenshot 4 - layer editing

In layer editing section, there are 9 tabs. In the table below, we highlight the needed customizations for this tutorial in the table below. The rest can be left on their default values. For more detailed description, please read Edit a layer page.

Tab	Fields	Customizations
Listing & Indexing	Icon	We upload a layar icon image.
	Category	Local information
	Detail description	Fill in "This is a layer which shows the location of the layar office in Amsterdam. It is a tutorial on creating a simple layer.It is created by Layar Technical Support."
	Minimum API version	Since we are creating a simple layer without any fancy feature implemented. Therefore, we set the Minimum API version to 2.1. NOTE that based on different features implemented in a layer, Minimum API version should be adjusted accordingly.
Look & feel	Banner Icon	Upload a banner icon(60x26).
Look & feel	Custom POI indicator Widgets (CIW)	Instead of using default POI icons, custom POI indicator widgets(CIW) can be defined here. We show the same layar icon image when POI is in Focus status and leave the others as default.
Coverage	Countries	Only list countries that this layer covers. Here we choose "Netherlands"
Coverage	Bounding Boxes	If POIs are only available in a city or specific region. Bounding boxes can be used to define that region. A layer with bounding boxes will be shown in the local tab when the user is in the defined region. In this layer, we set bounding boxes around Amsterdam.
Filters	Range slider	We add a "Range slider" to set search range.

3. Prepare the Database

After defining a layer on the publishing site, we can prepare the database that stores the information of POIs. We shall use a MySQL database with phpMyAdmin. In this tutorial, a table called POI_Table is used. More tables will be created in the coming tutorials to enable more advanced features, such as actions, 3D objects, etc.

We use the following SQL statement to create the table (based on the POI object description at GetPOIs-JSON Response on the Wiki):

CREATE TABLE IF NOT EXISTS `POI_Table` (
`id` varchar(255) NOT NULL,
`attribution` varchar(150) default NULL,
`title` varchar(150) NOT NULL,
`lat` decimal(20,10) NOT NULL,
`lon` decimal(20,10) NOT NULL,
`imageURL` varchar(255) default NULL,
`line4` varchar(150) default NULL,
`line3` varchar(150) default NULL,
`line2` varchar(150) default NULL,
`type` int(11) default '0',
`dimension` int(1) default '1',
`alt` int(10) default NULL,
`relativeAlt` int(10) default NULL,
`distance` decimal(20,10) NOT NULL,
`inFocus` tinyint(1) default '0',
`doNotIndex` tinyint(1) default '0',
`showSmallBiw` tinyint(1) default '1',
`showBiwOnClick` tinyint(1) default '1',
PRIMARY KEY (`id`)
) ENGINE=MyISAM DEFAULT CHARSET=utf8;

4. Gather POIs information

When the POI_Table is ready, we insert POIs into it. Google Maps is used to get the GPS coordinates for selected locations. You can also use other tools for this.

In our tutorial, we locate the Layar office (see screenshot below):

1) Search for "layar, amsterdam" at Google Maps.

2) Right click on the icon on the map and press "What's here". The Geo coordinates (latitude, longitude) will be displayed in the search field. In our case the coordinates are (52.374518, 4.9353).

screenshot 5 - POI Geo-coordinates

3) Add the POI information to the POI_Table below. The remaining fields are left as default for now.

screenshot 5 - POI_Table

This can also be done by running the following SQL statement:

INSERT INTO `POI_Table`

(`id`, `attribution`, `title`, `lat`, `lon`, `imageURL`, `line4`, `line3`, `line2`, `type`, `dimension`, `alt`, `relativeAlt`, `distance`, `inFocus`, `doNotIndex`, `showSmallBiw`, `showBiwOnClick`)

VALUES
('1', 'The Location of the Layar Office', 'The Layar Office', '52.3741180000', '4.9342500000', 'http://custom.layar.nl/Layar_banner_icon.png', '1019DW Amsterdam', 'distance:%distance%', 'Rietlandpark 301', 1, 1, NULL, NULL, '0.0000000000', 0, 0, 1, 1);

5. Build up a web service

Now that we have a POI in the database, it is time to build up a web service to fetch the POI information and return it back to the Layar platform. The returned POI information should be formatted in JSON. If PHP version 5.2 or above is used, JSON is supported natively. Otherwise, the JSON string needs to be constructed programatically.

In the layer definition, we have provided the POI URL which will be called to retrieve the POI information. Let's have a look at the PHP script.

To get started, we pre-define variables for the MySQL database connection.

/* Pre-define connection to the MySQL database, please specify these fields.*/

$dbhost = "localhost";

$dbdata = "database_name";

$dbuser = "database_username";

$dbpass = "database_password";

Read GetPOIs request

Based on the layer definition we just did, an HTTP GET request with defined parameters has been sent to the POI URL. A full list of request parameters can be found on GetPOIs-Request page. An example of GetPOIs request is:

http://custom.layar.nl/FirstTutorial_POI.php?lang=en&countryCode=NL&lon=4.887339&userId=6f85d06929d160a7c8a3cc1ab4b54b87db99f74b&developerId=4441&developerHash=26ec094e19db2c4a82ebafa200ea2a5e87a7d671&version=4.0&radius=2500&timestamp=1286357071952&lat=52.377544&layerName=layaroffice&accuracy=100

We first put needed parameter names from the GetPOI request in an array. In our tutorial, we need the following parameters:

layerName - The name of the layer defined on the publishing site.
lat - The latitude of the position where the user/phone is located.
lon - The longitude of the position where the user/phone is located.
radius - The search range within which POIs should be returned.

Then, we use $_GET, a php global variable, to retrieve these parameter values. The needed parameters are stored in an associative array named $value, which has parameter name as key and parameter value as value.

/* Put parameters from GetPOI request into an associative array named $value */

// Put needed parameter names from GetPOI request in an array called $keys.
$keys = array( "layerName", "lat", "lon", "radius" );

// Initialize an empty associative array.
$value = array();

try {
// Retrieve parameter values using $_GET and put them in $value array with parameter name as key.
foreach( $keys as $key ) {

    if ( isset($_GET[$key]) )
      $value[$key] = $_GET[$key];
    else
      throw new Exception($key ." parameter is not passed in GetPOI request.");
}//foreach
}//try
catch(Exception $e) {
echo 'Message: ' .$e->getMessage();
}//catch

Connect to MySQL database

Set up the connection to MySQL database and select the database which contains POI_Table table. In our tutorial, we use PDO, a PHP extension, to formalise database connection. For more information regarding using PDO, please see http://php.net/manual/en/book.pdo.php.

/* Connect to MySQL server. We use PDO which is a PHP extension to formalise database connection.
       For more information regarding PDO, please see http://php.net/manual/en/book.pdo.php.
*/

   // Connect to predefined MySQl database.
   $db = new PDO( "mysql:host=$dbhost; dbname=$dbdata", $dbuser, $dbpass, array(PDO::MYSQL_ATTR_INIT_COMMAND => "SET NAMES utf8") );

   // set the error reporting attribute to Exception.
   $db->setAttribute( PDO::ATTR_ERRMODE , PDO::ERRMODE_EXCEPTION );

Construct the JSON response

Now we are going to put values to the keys requested in the JSON response. The mandatory keys are:

layer: String; The name of the layer.
errorCode: Integer; 0 is ok. Use any error code between 20 and 29 to return a custom error message that will be displayed to the end-user.
errorString: String; The corresponding error message returned back to the user, visible in the AR view.
hotspots: Array of POIs; A list of returned POIs information.

To construct the JSON response:

/* Construct the response into an associative array.*/

   // Create an empty array named response.
   $response = array();

   // Assign cooresponding values to mandatory JSON response keys.
   $response["layer"] = $value["layerName"];

   // Use Gethotspots() function to retrieve POIs with in the search range.
   $response["hotspots"] = Gethotspots( $db, $value );

   // if there is no POI found, return a custom error message.
   if ( empty( $response["hotspots"] ) ) {
       $response["errorCode"] = 20;
        $response["errorString"] = "No POI found. Please adjust the range.";
   }//if
   else {
       $response["errorCode"] = 0;
       $response["errorString"] = "ok";
   }//else

A custom function called Gethotspots() is used to retrieve and put received POIs into an associative array. The returned values are assigned to $reponse["hotspots"].

Argument in the Gehotspots function:

db ; The handler of the database.
value ; An array which contains all the needed parameters retrieved from GetPOI request.

Return:

Array; An array of received POIs.

There are two tasks in this function:

1. Create SQL statement to fetch the POI information

Now we are going to create a SQL statement to retrieve POIs information from POI_Table. Please NOTE that only return parameters that are needed. For optional parameters that are not used, please remove them from the response or just return default values.

Only POIs within the defined search range (in our case, "radius" returned from the GetPOI request) are fetched. Returned POIs are sorted by distance and the first 50 POIs are selected. The calculation of the distance (in meters) between two locations is based on the Haversine formula. Please note that this way of calculation is not scalable for querying large databases.

In our tutorial, we use a combination of PDO::prepare() and PDO::execute() to prepare and execute the SQL query. These two PDO statements are used due to security reasons and will help prevent general SQL injection attacks.

2. Parse the retrieved POIs information

Sort out retrieved POIs information and put them in $reponse["hotspots"] associative array.

function Gethotspots( $db, $value ) {

/* Create the SQL query to retrieve POIs within the "radius" returned from GetPOI request.
       Returned POIs are sorted by distance and the first 50 POIs are selected.
       The distance is caculated based on the Haversine formula.
       Note: this way of calculation is not scalable for querying large database.
*/

// Use PDO::prepare() to prepare SQL statement.
// This statement is used due to security reasons and will help prevent general SQL injection attacks.
// ":lat1", ":lat2", ":long" and ":radius" are named parameter markers for which real values
// will be substituted when the statement is executed.
// $sql is returned as a PDO statement object.
$sql = $db->prepare( "
           SELECT id,
                   attribution,
                   title,
                   lat,
                   lon,
                   imageURL,
                   line4,
                   line3,
                   line2,
                   type,
                   dimension,
                   (((acos(sin((:lat1 * pi() / 180)) * sin((lat * pi() / 180)) +
                         cos((:lat2 * pi() / 180)) * cos((lat * pi() / 180)) *
                       cos((:long - lon) * pi() / 180))
                      ) * 180 / pi()) * 60 * 1.1515 * 1.609344 * 1000) as distance
           FROM POI_Table
           HAVING distance < :radius
           ORDER BY distance ASC
           LIMIT 0, 50 " );

// PDOStatement::bindParam() binds the named parameter markers to the specified parameter values.
$sql->bindParam( ':lat1', $value['lat'], PDO::PARAM_STR );
$sql->bindParam( ':lat2', $value['lat'], PDO::PARAM_STR );
$sql->bindParam( ':long', $value['lon'], PDO::PARAM_STR );
$sql->bindParam( ':radius', $value['radius'], PDO::PARAM_INT );

// Use PDO::execute() to execute the prepared statement $sql.
$sql->execute();

// Iterator for the response array.
$i = 0;

// Use fetchAll to return an array containing all of the remaining rows in the result set.
// Use PDO::FETCH_ASSOC to fetch $sql query results and return each row as an array indexed by column name.
$pois = $sql->fetchAll(PDO::FETCH_ASSOC);

/* Process the $pois result */

// if $pois array is empty, return empty array.
if ( empty($pois) ) {

   $response["hotspots"] = array ();

}//if
else {

   // Put each POI information into $response["hotspots"] array.
    foreach ( $pois as $poi ) {

       // If not used, return an empty actions array.
       $poi["actions"] = array();

       // Store the integer value of "lat" and "lon" using predefined function ChangetoIntLoc.
       $poi["lat"] = ChangetoIntLoc( $poi["lat"] );
       $poi["lon"] = ChangetoIntLoc( $poi["lon"] );

       // Change to Int with function ChangetoInt.
       $poi["type"] = ChangetoInt( $poi["type"] );
       $poi["dimension"] = ChangetoInt( $poi["dimension"] );

       // Change to demical value with function ChangetoFloat
       $poi["distance"] = ChangetoFloat( $poi["distance"] );

       // Put the poi into the response array.
       $response["hotspots"][$i] = $poi;
       $i++;
   }//foreach

}//else

return $response["hotspots"];
}//Gethotspots

Some custom functions used in Gethotspots() are:

ChangetoIntLoc(), which converts a decimal GPS latitude or longitude value to an integer by multiplying by 1000000.

// Convert a decimal GPS latitude or longitude value to an integer by multiplying by 1000000.
//
// Arguments:
// value_Dec ; The decimal latitude or longitude GPS value.
//
// Returns:
// int ; The integer value of the latitude or longitude.
//
function ChangetoIntLoc( $value_Dec ) {

return $value_Dec * 1000000;

}//ChangetoIntLoc

The ChangetoInt () function, which changes a string value to integer.

// Change a string value to integer.
//
// Arguments:
//   string ; A string value.
//
// Returns:
//   Int ; If the string is empty, return NULL.
//
function ChangetoInt( $string ) {

if ( strlen( trim( $string ) ) != 0 ) {

    return (int)$string;
}
else
   return NULL;
}//ChangetoInt

The ChangetoFloat() function, which changes a string value to float.

// Change a string value to float
//
// Arguments:
//   string ; A string value.
//
// Returns:
//   float ; If the string is empty, return NULL.
//
function ChangetoFloat( $string ) {

if ( strlen( trim( $string ) ) != 0 ) {

    return (float)$string;
}
else
   return NULL;
}//ChangetoFloat

Write to JSON and close up MySQL connection

Finally, we are going to write $JsonResponse array into JSON format. After this, we close up the connection to MySQL database.

/* All data is in $response, print it into JSON format.*/

   // Put the JSON representation of $response into $jsonresponse.
   $jsonresponse = json_encode( $response );

   // Declare the correct content type in HTTP response header.
   header( "Content-type: application/json; charset=utf-8" );

   // Print out Json response.
   echo $jsonresponse;

   /* Close the MySQL connection.*/

   // Set $db to NULL to close the database connection.
   $db=null;

Now, we have explained the PHP code. The source code including the POI_Table can be Downloaded here.

6. Testing the layer

There are two ways to test a layer:

API test page: It is available on the publishing site next to each layer. The test man can be placed anywhere your POIs are located. In our case, we just leave it as default. After adjusting the search slider to the right position, press "Load POIs" button to retrieve POIs.

screenshot 6 - API test page

On the phone: Layar application is currently available on Android(version 1.5 and above) and IPhone( 3GS and 4).

Please visit Test a layer to get more information on how to test a layer on the API test page and on the phone.

7. Publish the layer

Before request publication approval, please make sure that you test your layer against Layer testing instructions . Once your layer is approved, you can publish it to make it visible to the users. To publish the layer, you can press the "publish" button next to each layer under "layers" tab on the publishing site (see screenshot below). For more information, please read Publish a layer on the wiki.

In this tutorial, we provide the fixed location of the phone as (lat: 52.373801, lon: 4.890935), country is Netherlands. Now, let's try to find the layer office on the screen!!

Oops, we see the custom error message on the top right, no poi is within the range. Let's increase the search range to 3.5km to try it again. Now we find the layar office!

This is the end of our first tutorial, get started with your first layer and impress us!!

For any technical questions, please visit Layar Developer Support Environment. The Layar developer community is there to help you out!

First Layar Tutorial - Create a simple layer