GeoCENS JS API Interactive Tutorial

The GeoCENS JavaScript API allows developers to retrieve data from the GeoCENS Data Service. Here are a few interactive examples.

Note: Parts of this tutorial may stop working if the API key is revoked or the data is moved.

Include the Libraries

The JS API requires jQuery (1.10.1 or newer). Be sure to include it before including the GeoCENS JS API.


      <script src="javascripts/jquery.js" type="text/javascript" charset="utf-8"></script>
      <script src="javascripts/geocens.js" type="text/javascript" charset="utf-8"></script>

    

Create a Service Object

A service object allows you to retrieve specific sensors from the GeoCENS Data Service. You will need an account with the GeoCENS Data Service to generate an API token key; this key allows you to retrieve data from the Restful API. A registration page for the Data Service is coming soon.

Creating a service object is simple:


      var api_key = "57378dc18d74bef1051312e29a26f0b3";

      var service = new Geocens.DataService({
        api_key: api_key
      });

    
View on JSFiddle

Retrieve a List of Sensors

The list of sensors available for an API Key can be retrieved using the getSensors function on a GeoCENS Data Service object. If raw JSON objects are preferred instead of JS Objects, getRawSensors should be used.


      var api_key = "57378dc18d74bef1051312e29a26f0b3";

      var service = new Geocens.DataService({
        api_key: api_key
      });

      service.getSensors({
        done: function(sensors) {
          console.log("Get Sensors", sensors);
          alert(JSON.stringify(sensors));
        }
      });

      service.getRawSensors({
        done: function(data) {
          console.log("Get Raw Sensors", data);
          alert(JSON.stringify(data));
        }
      });

    

Retrieve a Sensor

A single sensor from the GeoCENS Data Service can be retrieved using this function.


      var api_key = "57378dc18d74bef1051312e29a26f0b3";

      var service = new Geocens.DataService({
        api_key: api_key
      });

      service.getSensor({
        sensor_id: "4ddecd5124661f9442cfca8be23f8dda",
        done: function(sensor) {
          console.log("Example Thirteen", sensor);
          alert(JSON.stringify(sensor.metadata));
        }
      });

    

Retrieve a Sensor's Datastreams

With a Sensor object, the list of datastreams for that sensor can be retrieved as raw JS objects or full Datastream objects. Raw is useful if you want to parse the data yourself, and can be retrieved with getRawDatastreams. Otherwise the regular getDatastreams function is more useful as it returns full Datastream objects with getTimeSeries functions defined.


      var api_key = "57378dc18d74bef1051312e29a26f0b3";

      var goGetDatastreams = function(sensor) {
        sensor.getDatastreams({
          done: function(datastreams) {
            console.log("Example Fourteen", datastreams);
            alert(datastreams);
          }
        });

        sensor.getRawDatastreams({
          done: function(data) {
            console.log("Example Fourteen", data);
            alert(data);
          }
        });
      };

      var service = new Geocens.DataService({
        api_key: api_key
      });

      service.getSensor({
        sensor_id: "4ddecd5124661f9442cfca8be23f8dda",
        done: function(sensor) {
          console.log("Example Fourteen", sensor);
          goGetDatastreams(sensor);
        }
      });

    

Retrieve a Datastream

With a Datastream object, we can now retrieve a datastream. There are two identifiers for each datastream: the sensor ID, and the datastream ID. (These are part of the GeoCENS Data Service specification.) Using these identifiers we can get the datastream.

Once we have the datastream, we can get the datastream attributes using the attributes() method.


      var api_key = "57378dc18d74bef1051312e29a26f0b3";

      var service = new Geocens.DataService({
        api_key: api_key
      });

      service.getDatastream({
        sensor_id: "4ddecd5124661f9442cfca8be23f8dda",
        datastream_id: "ccc92c6fe57dff592ff687d99c4ebf70",
        done: function(datastream) {
          console.log("Example Two", datastream);
          alert(JSON.stringify(datastream.attributes()));
        }
      });

    
View on JSFiddle

Retrieve a Datastream Time Series

The main use case of the JS API is retrieving observations from sensors, and this can be done using the getTimeSeries() method.


      var api_key = "57378dc18d74bef1051312e29a26f0b3";

      var goGetObservations = function(datastream) {
        datastream.getTimeSeries({
          start: new Date("2012-01-01T00:00:00Z"),
          end:   new Date("2013-01-01T00:00:00Z"),
          done:  function(seriesData) {
            console.log("Example Three", seriesData);
            alert(JSON.stringify(seriesData));
          }
        });
      };

      var service = new Geocens.DataService({
        api_key: api_key
      });

      service.getDatastream({
        sensor_id: "4ddecd5124661f9442cfca8be23f8dda",
        datastream_id: "ccc92c6fe57dff592ff687d99c4ebf70",
        done: goGetObservations
      });

    
View on JSFiddle

Create an OGC SOS Service Object

OGC SOS Service Objects allow you to retrieve observation data.

Creating an OGC SOS service object is simple:


      var service = new Geocens.SOS({
        service_url: "http://app.geocens.ca:8171/sos"
      });

    
View on JSFiddle

Retrieve SOS Observations

Once we have a service object for the SOS, we can retrieve the SOS Observations for an Offering and Observed Property.


      var service = new Geocens.SOS({
        service_url: "http://app.geocens.ca:8171/sos"
      });

      service.getObservation({
        offering: "Temperature",
        property: "urn:ogc:def:property:noaa:ndbc:Water Temperature",
        done: function (observations) {
          console.log("Example Five", observations);
          alert(JSON.stringify(observations[0].attributes()));
        }
      });

    
View on JSFiddle

Retrieve an Observation Time Series

Each Observation object has a method for retrieving the series records.


      var goGetRecords = function(observations) {
        observations[0].getTimeSeries({
          start: new Date("2012-01-01T00:00:00Z"),
          end:   new Date("2012-06-01T00:00:00Z"),
          done:  function(seriesData) {
            console.log("Example Six", seriesData);
            alert(JSON.stringify(seriesData));
          }
        });
      };

      var service = new Geocens.SOS({
        service_url: "http://app.geocens.ca:8171/sos"
      });

      service.getObservation({
        offering: "Temperature",
        property: "urn:ogc:def:property:noaa:ndbc:Water Temperature",
        done: goGetRecords
      });

    
View on JSFiddle

Retrieve an Observation Sensor Description

Each Observation object has a method for retrieving the sensorML document for its procedure.


      var goGetDescription = function(observations) {
        observations[0].describe({
          done: function(sensorML) {
            console.log("Example Seven", sensorML);
            alert(JSON.stringify(sensorML));
          }
        });
      };

      var service = new Geocens.SOS({
        service_url: "http://app.geocens.ca:8171/sos"
      });

      service.getObservation({
        offering: "Temperature",
        property: "urn:ogc:def:property:noaa:ndbc:Water Temperature",
        done: goGetDescription
      });

    
View on JSFiddle

Including the Chart Module

There is an optional module for drawing time series graphs for observations and datastreams. It requires HighStock (1.3.2 or newer), jQuery (1.10.1 or newer), and the core GeoCENS JS API (0.4.1 or newer).


      <script src="javascripts/jquery.js" type="text/javascript" charset="utf-8"></script>
      <script src="javascripts/geocens.js" type="text/javascript" charset="utf-8"></script>
      <script src="javascripts/highstock.js" type="text/javascript" charset="utf-8"></script>
      <script src="javascripts/geocens-chart.js" type="text/javascript" charset="utf-8"></script>

    

Be sure to include HighStock before including the GeoCENS Chart module!

Datastream Time Series Chart

The GeoCENS Chart module is a jQuery plugin, so it is invoked using a jQuery selector. By passing the data through the callbacks, the datastream time series can be customized before being plotted on the chart.


      // Draw the chart after time series is returned
      var drawChart = function(seriesData, datastream) {
        var chart = $("#chart").GeocensChart({
          datastream: datastream
        });
      };

      // Retrieve the time series after datastream is returned
      var getSeries = function(datastream) {
        datastream.getTimeSeries({
          start: new Date("2012-01-01T00:00:00Z"),
          end:   new Date("2013-01-01T00:00:00Z"),
          done:  drawChart
        });
      };

      // Retrieve the datastream
      Geocens.DataService.getDatastream({
        api_key: "57378dc18d74bef1051312e29a26f0b3",
        sensor_id: "4ddecd5124661f9442cfca8be23f8dda",
        datastream_id: "ccc92c6fe57dff592ff687d99c4ebf70",
        done: getSeries
      });

    
View on JSFiddle

Observation Time Series Chart

Very similarly to the datastream chart, OGC SOS observation data is straight forward.


      // Draw the chart after time series is returned
      var drawChart = function(seriesData, observation) {
        var chart = $("#chart2").GeocensChart({
          observation: observation
        });
      };

      // Retrieve the time series after observations is returned (note plural)
      var getSeries = function(observations) {
        observations[0].getTimeSeries({
          start: new Date("2012-01-01T00:00:00Z"),
          end:   new Date("2012-06-01T00:00:00Z"),
          done:  drawChart
        });
      };

      // Retrieve the observations
      Geocens.SOS.getObservation({
        service_url: "http://app.geocens.ca:8171/sos",
        offering: "Temperature",
        property: "urn:ogc:def:property:noaa:ndbc:Water Temperature",
        done: getSeries
      });

    
View on JSFiddle

Including the Map Module

There is an optional module for adding observations and datastreams to a map as markers. It requires Leaflet (0.6.0 or newer), jQuery (1.10.1 or newer), and the core GeoCENS JS API (0.4.1 or newer).


      <script src="javascripts/jquery.js" type="text/javascript" charset="utf-8"></script>
      <script src="javascripts/geocens.js" type="text/javascript" charset="utf-8"></script>
      <script src="javascripts/leaflet.js" type="text/javascript" charset="utf-8"></script>
      <script src="javascripts/geocens-map.js" type="text/javascript" charset="utf-8"></script>

    

Be sure to include Leaflet before including the GeoCENS Map module!

Add OGC SOS Observations to a Map

A module is added to Leaflet to make adding OGC SOS observations easy.


        L.Icon.Default.imagePath = "images";

        var map = L.map('map1', {
              center: [51.07993, -114.131802],
              zoom: 3
        });

        L.tileLayer('http://{s}.tile.osm.org/{z}/{x}/{y}.png', {
            attribution: '&copy; <a href="http://osm.org/copyright">OpenStreetMap</a> contributors'
        }).addTo(map);

        var mapObservations = function(observations) {
          L.geocens(observations).addTo(map);
        };

        Geocens.SOS.getObservation({
          service_url: "http://app.geocens.ca:8171/sos",
          offering: "Temperature",
          property: "urn:ogc:def:property:noaa:ndbc:Water Temperature",
          done: mapObservations
        });

    
View on JSFiddle

Add Data Service Datastreams to a Map

A module is added to Leaflet to make adding GeoCENS Data Service datastreams to a map easy.


        L.Icon.Default.imagePath = "images";

        var map = L.map('map2', {
              center: [51.07993, -114.131802],
              zoom: 3
        });

        L.tileLayer('http://{s}.tile.osm.org/{z}/{x}/{y}.png', {
            attribution: '&copy; <a href="http://osm.org/copyright">OpenStreetMap</a> contributors'
        }).addTo(map);

        var mapDatastream = function(datastream) {
          L.geocens(datastream).addTo(map);
        };

        Geocens.DataService.getDatastream({
          api_key: "57378dc18d74bef1051312e29a26f0b3",
          sensor_id: "4ddecd5124661f9442cfca8be23f8dda",
          datastream_id: "ccc92c6fe57dff592ff687d99c4ebf70",
          done: mapDatastream
        });

    
View on JSFiddle

Add OGC SOS Observations to a Map with Clustering

First, include the clustering plugin CSS and JS:


      <link rel="stylesheet" href="stylesheets/MarkerCluster.css"></link>
      <link rel="stylesheet" href="stylesheets/MarkerCluster.Default.css"></link>
      <script src="javascripts/leaflet.markercluster.js" type="text/javascript" charset="utf-8"></script>

    

Then use the clustering plugin as usual when creating the map. A fullscreen example version is also available.

        L.Icon.Default.imagePath = "images";

        var map = L.map('map1', {
              center: [51.07993, -114.131802],
              zoom: 3
        });

        var markers = new L.MarkerClusterGroup();

        L.tileLayer('http://{s}.tile.osm.org/{z}/{x}/{y}.png', {
            attribution: '&copy; <a href="http://osm.org/copyright">OpenStreetMap</a> contributors'
        }).addTo(map);

        var mapObservations = function(observations) {
          markers.addLayer(L.geocens(observations));
          map.addLayer(markers);
        };

        Geocens.SOS.getObservation({
          service_url: "http://app.geocens.ca:8171/sos",
          offering: "Temperature",
          property: "urn:ogc:def:property:noaa:ndbc:Water Temperature",
          done: mapObservations
        });

    
View on JSFiddle