Javascript API Guide

Getting started

First you need to include the API into your web page. The API is readily available for use here: api.giscloud.com/1/api.js.

Start by placing this script tag in the head section of your web page.

<script src="https://api.giscloud.com/1/api.js" type="text/javascript"></script>

A simple mapping application

Now that you have included the API, you can proceed by making a simple mapping application like this.

A simple mapping application

This application has a map viewer and a toolbar.

The viewer is created by supplying the giscloud. Viewer constructor with an id of the div container element and an id of a map in the GIS Cloud public directory. Once this has been done, a map viewer is embedded into the container div.

// create a viewer
var viewer = new giscloud.Viewer("mapViewer", mapId);

The toolbar above the map is a UI component included in the API. It is created using the giscloud.ui.Toolbar constructor.

// create a toolbar
var toolbar = new giscloud.ui.Toolbar({
   viewer: viewer,
   container: "toolbar",
   defaultTools: ["pan", "zoom", "full", "measure"]
});

The constructor is passed an object containing some of the toolbar properties:

Later in the reference you will learn how you can create and style your own tools to control the map viewer behaviour.

giscloud.ready()

Please note that the viewer and toolbar creation code is inside a function passed to giscloud.ready(). You should use this feature when your code depends on the DOM being fully loaded. See demo.

Getting data from GIS Cloud

GIS Cloud is more than just mapping. Through the JS API you can retrieve and manipulate data stored on GIS Cloud. Take a look at this example which lists all the public maps and their layers.

Getting maps and layers data

This example shows two methods used in data retrieval, giscloud.maps.list() and giscloud.layers.byMapId(). Those methods are used to get a list of GIS Cloud public maps and layers in those maps respectively.

// the only argument of the giscloud.maps.list() is the callback function
giscloud.maps.list(function(mapdata) {
    var i, k, map;
 
    // mapdata contains an array of giscloud.Map objects
    for (i = 0, k = mapdata.length; i < k; i++) { 
         map = mapdata[i];
         //...
     }
});

Method giscloud.maps.list() makes a call to the server asking for all the maps in the public directory. Once the data is received it is passed to the callback function. Data is in form of an array withgiscloud.Map objects.

See the reference for

// arguments of the giscloud.layers.byMapId()
// are the id of the map and a callback function
giscloud.layers.byMapId(mapId, function(layerdata) {
    var i, k, layer;
 
    // layerdata contains an array of giscloud.Layer objects
    for (i = 0, k = mapdata.length; i < k; i++) { 
        layer = layerdata[i];
        //...
    }
});

Method giscloud.layers.byMapId() makes a call to the server asking for the layers of the map specified by the mapId argument. Upon receiving the data, it is passed to the callback function as an argument. Layers data is in form of an array with giscloud.Layer objects.

See the reference for

Examples and demos

Take a look at these example apps to see more features of the GIS Cloud JS API in use. The examples come with an explanation and excerpts from the code and you can always take a look at the source.

These are also available on GitHub.

Questions? Contact us