Javascript quick start

GaiaSup can be used via two major means: REST API and language bindings. Currently we have language binding for JavaScript, but others will be coming. We'll use JavaScript as the main example in the following tutorial, though the general concepts will be similar for other language bindings.

It is very easy to start using GaiaSup with the Javascript language binding. Once you have created your account and a project, you will be given an apikey which is used to uniquely identify your application.

To use GaiaSup, the three main steps are:


1. Initialize a Node

The first step is to create a node, which is basically a representation in a particular layer within your registered spatial application.

Your spatial application can be an online game or something that runs on the mobile phone. All the layers reside on the same coordinate space for a given app, but they do not interfere with each other. So for example, you could have one layer storing all the user positions for a mobile application, and another layer to store the info about local restaurants for users to query. Any publish or subscribe (pub/sub) actions at a given layer do not interfere with the pub/sub at other layers.

Each node also has a name, which is provided by your application. Each node thus can be uniquely identified by a string in the format of "apikey:layer:name", which is called an ident.

In the following sample, we assume that there's a 'self' object with node name, and x, y, z coordinates for a user. For example:


// set info about current node
var self = {x:      120, 
            y:      130,
            z:      0,
            radius: 200,
            name:   "Deep Blue"


To create a node, you can use the following code, but filled with your own apikey, layer, and name, plus three optional callback functions. 


// create a GaiaSup node
var node = new GAIASUP.node();

// init with layer & node name
        apikey:     "52249ae526761f994ed197e9ca415bf4d993134b",
        layer:      "default",
        pos_CB:     positionCallback,
        msg_CB:     messageCallback


For the callbacks, 'positionCallback' is called whenever neighboring nodes within your subscribed area(s) have updated their positions. For example:


// callback when neighbor positions are updated
var positionCallback = function (node_list) {

    // print neighbor info
    updateOutput('\n' + Object.keys(node_list).length + ' neighbors:');
    for (var ident in node_list)
        updateOutput('ident: ' + ident + ' (' + node_list[ident].x + ', ' +
                                                node_list[ident].y + ', ' +
                                                node_list[ident].z + ')');


'messageCallback', on the other hand, is invoked whenever nodes within your subscribed area(s) have published a string message, and a sample callback may look like this:


// callback when a message is received
var messageCallback = function (msg_list) {

    // print out message list
    for (var i=0; i < msg_list.length; i++) {
        var msg = msg_list[i];
        updateOutput(msg.ident + ': ' + msg.msg);


Optionally, you can also provide a "doneCallback" to notify when the init process is done, this is provided after the init parameters.


2. Subscribe Nearby Updates

The second step to take after initialization is to subscribe for some area near your node. You will first need to publish your position once, before performing a subscription of a given nearby radius:


// callback when initialization is done
var doneCallback = function () {

        pos: [self.x, self.y, self.z]

    // once done, perform subscribe nearby
    function () {
            radius:     self.radius


Note that in the above sample code, we perform the subscription within the "doneCallback," which is called after node is initialized. But you're free to put it anywhere else to perform a basic subscription.


3. Publish Your Positions

Once you have subscribed successfully, you can simply start to update node position whenever it occurs. Whether your node changes its position via GPS tracking or user input. You can use the following code to update:


// publish position change
    pos: [self.x, self.y, self.z]


In this case, self contains the x, y, and z coordinate of the updated coordinates.


4. Wrap It Up

So to make it all work, we build a simple HTML page where you can see how the change in node position (controlled by a user moving UP/DOWN/LEFT/RIGHT arrows) is published via GaiaSup, and how you can learn of neighboring nodes' ident and their positions.

Who's online

There are currently 0 users online.

Go to top