Getting started with the GIS Cloud JavaScript API

  1. Getting started with the GIS Cloud JavaScript API
    1. Include the API into your web page
    2. A simple mapping application
    3. Getting data from GIS Cloud
    4. Examples and demos

Here are some examples to help you get started.
See the full API reference here.

Include the API into your web page

The API is readily available for use here: http://api.giscloud.com/1/api.js. Start by placing this script tag in the head section of your web page.


<script src="http://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:

viewer
The viewer object we used for the map.
container
Id of a div element on the page to where the toolbar is rendered.
defaultTools
Array of tools already defined in the API.

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

  • giscloud.maps – object for map data manipulation here.
  • giscloud.Map – class representing GIS Cloud maps here.
 // 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

  • giscloud.layers – object for layer data manipulation here.
  • giscloud.Layer – class representing GIS Cloud map layers here.

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.