Locago

Tutorial: API connected layer

This tutorial will show you how to make already dynamic location data available on Locago. Most of the layers available on Locago are not personal favorite places but connections to other services, other APIs.

There are many open APIs available today. Maybe you have your own API that you want to make available on a mobile phone. A page where you can find open APIs is Programmable Web.

In this tutorial you will make the data from the Tixik API available on Locago.

Tixik is an open API to access a collection of famous places around the world. The data is accessible through HTTP. It uses the REST protocol and the data is formatted in XML.

This tutorial will use cURL to transfer data through HTTP. It will use PHP as server language. Please use languages and tools that you are comfortable with.

You can download all the files needed to create the tutorial layer here.
You can also download the modified files needed to create the further developed tutorial layer here.

The steps to create this layer are:


Start the tutorial

Step 1 - Study the Tixik API

A description of how to use the API is available on the English Tixik API page. . Please study your API closely before trying to create a Locago layer that accesses it.

In this part of the tutorial we will only use the "nearby"-search in the Tixik API. See how to develop the layer further here.

To make a "nearby" search we need to send the Locago user's position to the API. The response will be a XML formatted list of famous places. The amount of places can be limited with a parameter.

The response is structured as follows:

<tixik response="ok" >
<items>
<item>
<id> string </id>
<name> string </name>
<description> string(100) </description>
<tn> string </tn>
<gps_x> string(13) </gps_x>
<gps_y> string(13) </gps_y>
</item>
</items>
</tixik>

If you are using another API please study how the response is structured.

Up Next >

Step 2 - Create the IGEO file

The IGEO file store the geo data. When connected to an API the geo data depends on the response of the API.

Create an IGEO file with this content:

<?php
$httpCallString = 'http://en.tixik.com/api/nearby?';
 
$igeo = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>";
$igeo .= "<geodata>";
 
$paramsMissing .= true;
 
if(isset($_GET['y'])) {
$lat = $_GET['y'];
} else {
$paramsMissing = true;
}
 
if(isset($_GET['x'])) {
$lon = $_GET['x'];
} else {
$paramsMissing = true;
}
 
if($paramsMissing) {
$ok = false;
} else {
$httpCallString .= 'lat='.$lat.'&lng'.$lon;
 
/* cURL call */
$curl = curl_init($httpCallString);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$res = curl_exec($curl);
 
/* translate the response */
$sxe = new SimpleXMLElement($res);
$response = $sxe->attributes()->response;
if($response == "ok") {
$items = $sxe->items;
$ok = true;
} else {
$ok = false;
}
}
 
if(!$ok) {
$igeo .= "</geodata>";
} else {
 
foreach($items->item as $item) {
$name = $item->name;
$desc = $item->description;
$imageURL = $item->tn;
$URL = $item->url;
$lat = $item->gpx_x;
$lon = $item->gps_y;
 
/* create marker */
$igeo .= "<Marker name=\"" .$name."\" text=\"" .$URL."\" x=\"" .$lon."\" y=\"" .$lat."\"/> ";
}
 
$igeo .= "</geodata>";
}
 
/* headers */
header('Content-type:text/xml; charset=UTF-8');
header('Expires: Sat, 26 Jul 1997 05:00:00 GMT');
echo $igeo;
 
exit;
?>

Save the file as tixik.php.igeo.
Hint! Create an example of the IGEO file first and check that it works before letting PHP generate it.

The result, when presented on the map, is also described by the IGEO file. The text-attribute of each place can contain not only plain text. See the IGEO documentation for more information. The layer can be further developed, see here where redirect is used to make the information about the famous place more complete.

< Back Up Next >

Step 3 - Create IDOC file

The IDOC file describes how the layer page is presented to the Locago user and how the layer itself works.

Create an IDOC file with this content:

<?xml version="1.0" encoding="UTF-8" ?>
<idoc title="API tutorial layer" icon="tixik.png" >
 
<!-- Part: Layer-->
<layer>
<info>
This (example) layer shows how a layer can be connected to an API. The geo data is collected from Tixik API - famous places around the world.
</info>
<symbolLayer name="Places" dataset="tutorial_tixik.php.igeo" webServiceFormat="igeo" />
<tag name="Example" />
</layer>
 
<!-- handlers -->
<handler id="dataloaded" action="layer.viewSelection(1); app.showMap();" />
<handler id="show" action="doc.fields.thex.value=map.centerX; doc.fields.they.value=map.centerY;" />
 
<!-- Part: Page -->
<style fontSize="12" fontStyle="bold" alignX="middle" >
API tutorial layer
</style>
<br/>
<br/>
Search for famous places around the center of the map
<br/>
<br/>
The center of the map
<br/>
<section id="thex" title="Longitude" value="" readonly="true" />
<section id="they" title="Latitude" value="" readonly="true" />
<br/>
<section title="Search" action="layer.load({sublayer:'Places', handler:doc.handlers.dataloaded, arg:{x:map.centerX, y:map.centerY}})" />
</idoc>

Save the file as tixik.idoc, or download the file from here.
Save the icon: as tixik.png

As in the dynamic layer tutorial a handler is used to show the map when the data is loaded.

The position on the map is collected with the IScript command map.centerX and map.centerY. See the IScript documentation for more information.
Note! x stands for the longitude coordinate and y stands for the latitude coordinate in Locago

< Back Up Next >

Step 4 - Make the content available and publish it on Locago

Make the content available

A Web server is needed to make the content available to Locago. Place all the files in the same directory, or change the path to the files in relation to the placement of the files. Relative path is allowed.

Publish the page on Locago

To publish a page you need to be signed in. If you do not have an account you need to create one first. It is free.

The layer URL to be given on the publisher page is the path to the IDOC file.

After publishing your layer you can add it to your mobile phone from the head menu in Locago by searching for the title. You can also view the layer in the Locago web demo by clicking the 'View' option on the publisher page.
Note! Your layer may not be visible if you browse the Locago layers by tag. Only the top ten rated layers in every tag category are visible. This may be changed in Locago in the future.

Manage published layers

When logged in you can manage all your already published layers on the publisher page. If any content is changed, please update your layer by clicking on 'Update'.

< Back Up Next >

Develop the layer further

One way to layer development is to use more of the Tixik API functionalities, where you can search for famous places, limit the number of search result and reverse geocode.

Another way of developing the layer further is to create an IDOC page for each place. Instead of only a small description of the place, the page can use all of the information from the API to create a greater usability.

With the improved layer the Locago user can search for a famous place and get more information about the place.

The steps to further develop the layer are:

 

IGEO file #1

Make these changes to the IGEO file:

<?php
$httpCallString = 'http://en.tixik.com/api/';
 
$igeo = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>";
$igeo .= "<geodata>";
 
$paramsMissing .= true;
 
if(isset($_GET['search'])) {
$lat = $_GET['search'];
} else {
$search = true;
}
 
/* create API call */
if($search) {
$httpCallString .= 'search?s='.$search;
} else {
$paramsMissing = true;
if(isset($_GET['y'])) {
$lat = $_GET['y'];
} else {
$paramsMissing = true;
}
 
if(isset($_GET['x'])) {
$lon = $_GET['x'];
} else {
$paramsMissing = true;
}
 
if($paramsMissing) {
$ok = false;
} else {
$httpCallString .= 'nearby?lat='.$lat.'&lng'.$lon;
}
}
 
if($paramsMissing) {
$ok = false;
} else {
/* cURL call */
$curl = curl_init($httpCallString);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$res = curl_exec($curl);
 
/* translate the response */
$sxe = new SimpleXMLElement($res);
$response = $sxe->attributes()->response;
if($response == "ok") {
$items = $sxe->items;
$ok = true;
} else {
$ok = false;
}
}
 
if(!$ok) {
$igeo .= "</geodata>";
} else {
 
foreach($items->item as $item) {
$name = $item->name;
$desc = $item->description;
$imageURL = $item->tn;
$URL = $item->url;
$lat = $item->gpx_x;
$lon = $item->gps_y;
 
/* create marker */
$igeo .= "<Marker name=\"" .$name."\" text=\"" .$URL."\" x=\"" .$lon."\" y=\"" .$lat."\"/> ";
}
 
$igeo .= "</geodata>";
}
 
/* headers */
header('Content-type:text/xml; charset=UTF-8');
header('Expires: Sat, 26 Jul 1997 05:00:00 GMT');
echo $igeo;
 
exit;
?>

Save the file as tutorial_tixik.php.igeo

This consists mostly of changes to the PHP code and the connection to the API. If the parameters from the IDOC are a longitude and latitude value nearby-call is used. If the search parameter is set, search around the world is used instead with this search word.
Hint! By opening the IGEO file in a Web browser you can test wheater the server language behaves as wanted.

Top of page
< Back Up Next >

IDOC file

Make the following changes to the IDOC file:

<?xml version="1.0" encoding="UTF-8" ?>
<idoc title="API tutorial layer" icon="tixik.png" >
 
<!-- Part: Layer-->
<layer>
<info>
This (example) layer shows how a layer can be connected to an API. The geo data is collected from Tixik API - famous places around the world.
</info>
<symbolLayer name="Places" dataset="tutorial_tixik.php.igeo" webServiceFormat="igeo" />
<tag name="Example" />
</layer>
 
<!-- handlers -->
<handler id="dataloaded" action="layer.viewSelection(1); app.showMap();" />
<handler id="show" action="doc.fields.thex.value=map.centerX; doc.fields.they.value=map.centerY;" />
 
<!-- Part: Page -->
<style fontSize="12" fontStyle="bold" alignX="middle" >
API tutorial layer
</style>
<br/>
<br/>
Search for famous places around the center of the map
<br/>
<br/>
The center of the map
<br/>
<section id="thex" title="Longitude" value="" readonly="true" />
<section id="they" title="Latitude" value="" readonly="true" />
<br/>
<section title="Search" action="layer.load({sublayer:'Places', handler:doc.handlers.dataloaded, arg:{x:map.centerX, y:map.centerY}})" />
<br/>
<br/>
<section id="search" title="Enter search phrase" value="" />
<space/><space/>
<section title="Search with phrase" action="layer.load({sublayer:'Places', handler:doc.handlers.dataloaded, arg:{search:doc.fields.search.value}})" />
<br/>
</idoc>

Save the file as tutorial_tixik.idoc, or download it from here

The text field and button are added to the IDOC page. The important things are the arguments to the IGEO file from the search button.

Top of page
< Back Up Next >

placepage.idoc

This is the page that describes how a famous place should be presented to the Locago user when selecting a search result.

Create a new IDOC file as follows:

<?php
$params = urldecode($_GET['params']));
 
/* decode params */
$tmp = explode("&", $params);
$k = 0;
foreach($tmp as $t) {
$pair = explode("=", $t);
$value[$k++] = $pair[1];
}
 
$name = $value[0];
$desc = $value[1];
$imgURL = $value[2];
$url = $value[3];
 
$idoc = "<?xml version='1.0' encoding='UTF-8'?>";
$idoc = "<idoc>";
 
$idoc = "<style name='title' fontSize='12' fontStyle='bold' alignX='middle'/>";
 
$idoc = "<br/>";
$idoc = "<style alignX='middle'>";
$idoc = "<image ref='".$imgURL.>";
$idoc = "</style>";
$idoc = "<br/>";
$idoc = "<br/>";
 
$idoc = "<style apply='title'>";
$idoc = $name;
$idoc = "</style>";
$idoc = "<br/>";
$idoc = "<br/>";
 
$idoc = $desc;
 
$idoc = "<br/>";
$idoc = "<br/>";
 
$idoc = "<button label='Read more...' action=\"app.browse('".$url."')\" linkStyle='true'/>";
$idoc = "<br/>";
$idoc = "<br/>";
$idoc = "</idoc>";
 
/* headers */
header('Content-type:text/xml; charset=UTF-8');
header('Expires: Sat, 26 Jul 1997 05:00:00 GMT');
echo $idoc;
 
exit;
?>

Save the file as placepage.idoc

The action to the link styled button open the phone browser at the actual link. See the IScript documentation for more information.

Top of page
< Back Up Next >

IGEO file #2

The IGEO file must be modified to connect the placepage.idoc to each place and send the corresponding parameters. As usual, the HTTP protocol requires well formatted strings, this way of solving the problem may not be the best.

Make the following changes to the already modified IGEO file:

<?php
$httpCallString = 'http://en.tixik.com/api/';
 
$igeo = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>";
$igeo .= "<geodata>";
 
$paramsMissing .= true;
 
if(isset($_GET['search'])) {
$lat = $_GET['search'];
} else {
$search = true;
}
 
/* create API call */
if($search) {
$httpCallString .= 'search?s='.$search;
} else {
$paramsMissing = true;
if(isset($_GET['y'])) {
$lat = $_GET['y'];
} else {
$paramsMissing = true;
}
 
if(isset($_GET['x'])) {
$lon = $_GET['x'];
} else {
$paramsMissing = true;
}
 
if($paramsMissing) {
$ok = false;
} else {
$httpCallString .= 'nearby?lat='.$lat.'&lng'.$lon;
}
}
 
if($paramsMissing) {
$ok = false;
} else {
/* cURL call */
$curl = curl_init($httpCallString);
curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
$res = curl_exec($curl);
 
/* translate the response */
$sxe = new SimpleXMLElement($res);
$response = $sxe->attributes()->response;
if($response == "ok") {
$items = $sxe->items;
$ok = true;
} else {
$ok = false;
}
}
 
if(!$ok) {
$igeo .= "</geodata>";
} else {
 
foreach($items->item as $item) {
$name = $item->name;
$desc = $item->description;
$imageURL = $item->tn;
$URL = $item->url;
$lat = $item->gpx_x;
$lon = $item->gps_y;
 
/* create marker */
$igeo .= "<Marker name=\"" .$name."\" text=\"redirect:placepage.idoc?params=" .$tmp."\" x=\"" .$lon."\" y=\"" .$lat."\"/> ";
}
 
$igeo .= "</geodata>";
}
 
/* headers */
header('Content-type:text/xml; charset=UTF-8');
header('Expires: Sat, 26 Jul 1997 05:00:00 GMT');
echo $igeo;
 
exit;
?>

Save the file as tutorial_tixik.php.igeo.

Top of page
< Back Up Next >

Re-publish

On the Publisher page you can use the Update button, if the files are uploaded to the same place as before.

To continue, you may make it possible to limit the search result and/or make it possible to reverse geocode a position. See the Tixik API for information.
Hint! 100128 - The parameters, longitude and latitude, for the Localize-call seem to be reversed.

Top of page
< Back Up