dataseed data visualization

menu expand

For Developers

Introduction

It's easy to build real-time data-driven visualisations, or add analytics to your existing applications. We provide a hosted back-end with analytics capabilities, into which you can load your data via a RESTful API, or from Amazon S3.

The simplest way to start is to load in a dataset from a csv and fork our example Datacube visualisation on Github, it's written entirely in js and provided as open source under the GPL2 license.

Benefits

  • Powerful cloud-hosted OLAP analytics engine

  • Support for real-time data streams

  • RESTful JSON API for importing and querying data

  • Open-source javascript front-end, built with backbone.js, grunt.js, bower, bootstrap - all the good stuff

  • SVG charts build with d3.js

  • Versatile multi-dimensional data model

  • Linked-data approach. Compatible with Datacube and SDMX

  • Statistical operations including mean, min, max, variance, sum of squares and standard deviation

  • Responsive and ready for desktop / tablet / mobile

Getting Started

Glossary

Basic Embedding

The simplest way to embed a visualisation is to use the "Export" button on the visualisation in Dataseed. The export will provide you with a snippet of HTML that you can copy-and-paste into your site.

For help on more advanced embedding have a look at the Javascript Library.

Drupal

For easy Drupal integration check out the Dataseed module on drupal.org

Javascript Library

The Dataseed Javascript Library allows visualisations to be integrated with existing Javascript applications. A working knowledge of Javascript is necessary to use the library, for a simpler method of including visualisations on your site see Basic Embedding.

The library consists of models and views for fetching and rendering visualisations built on the Backbone.js framework with RequireJS used for module and dependency handling.

Dependencies

The library uses the Node.js platform for building the JS and related tasks. You can install Node.js using the packages on the download page or through your OS's package manager.

Setup

  1. First, grab a copy of the library from Github: git clone https://github.com/dataseed/dataseed-visualisation.git
  2. Enter the repo: cd dataseed-visualisation
  3. Install dependencies with npm: npm install
  4. Get third-party libraries using Bower: bower install

To test that everything has been setup correctly open the index-src.html file in a browser and you should see the mortality visualisation.

Building

The build process is managed by Grunt and includes Javascript aggregation and minification as well as LESS compilation. To run the build use:

grunt build

To test that the build completed successfully open the index.html file in a browser.

Example

The following example demonstrates a simple web application that renders a visualisation when a user clicks a button:

<!doctype html>
<html dir="ltr" lang="en">
<head>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
    <title>Dataseed Interactive Data Visualization</title>
    <meta name="viewport" content="width=device-width" />
    <!--[if lt IE 9]>
      <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
    <![endif]-->
    <link href="src/less/dataseed.less" rel="stylesheet/less" type="text/css" />
    <script src="src/components/less/dist/less-1.4.0.js"></script>
</head>
<body>
    <button id="start">Show me the visualisation!</button>
    <div id="vis"></div>
    <script src="src/components/requirejs/require.js" data-main="src/js/config"></script>
    <script>
        $(document).ready(function() {
            $('#start').click(function() {
                require(['./dataseed/views/dataset', 'app'], function(DatasetEmbedView) {
                    new DatasetEmbedView({
                        'el': $('#vis'),
                        'id': 'mortality',
                        'visualisation_id': '1'
                    });
                });
            });
        });
    </script>
</body>
</html>

REST API

Introduction

The API for Dataseed is implemented as a set of JSON resources (e.g. a Visualisation), each with their own URL. The resources may be read or altered using the standard HTTP verbs. We have tried to follow RESTful principals in the design of the API wherever possible.

The examples in this documentation use the cURL command line tool to interact with the API. If you have cURL installed (Linux and OS X users should have it by default) you can copy and paste the commands into a terminal to see them in action! For authenticated commands you'll need to replace the example account details with your own (see Authentication).

Requests

Requests to the API must always specify an Accept header with the JSON MIME type (i.e. "application/json"). So you could fetch a public dataset using:

curl -H'Accept: application/json' http://dataseedapp.com/api/datasets/mortality

When sending data to the API you must also specify the MIME type of your request using the Content-Type header header. The following example shows how to add an observation to an existing dataset:

curl -u'dataseed@example.com:password' -H'Accept: application/json' -H'Content-type: application/json' http://dataseedapp.com/api/datasets/my-dataset/observations -d'{ "observations": [ { "id": "o1234", "age": "26", "gender": "M" } ] }'

Responses

The are two classes of response returned by the API, indicated by the HTTP status code:

200/300: Success

The request succeeded. When creating or updating resources a 303 code will be returned. The URL the resource should be fetched from is specified in the Location header.

{
    "status": 200,
    "message": "Created"
}
400: Bad Request

The request failed because it was invalid. A general error message will be provided in the returned JSON as well as more specific errors when applicable.

{
    "status": 400,
    "message": "Invalid",
    "errors": {
        "label": "Required",
        "public": "Required"
    }
}

Authentication

All requests must be authenticated except when reading Datasets or Visualisations that are public. Currently, the only supported authentication method is HTTP Basic Authentication. The username and password should be the same ones you use to login with (if you haven't already got an account sign-up for one now).

So, for example, to fetch a private dataset you would do the following:

curl -u'dataseed@example.com:password' -H'Accept: application/json' http://dataseedapp.com/api/datasets/my-dataset

Dataset

Read

Request
curl -H'Accept: application/json' http://dataseedapp.com/api/datasets/mortality
Response
{
    "id": "mortality",
    "label": "Mortality",
    "public": true,
    "imports": [],
    "fields": [
        {
            "id": "year",
            "label": "Year",
            "description": null,
            "aggregations": [],
            "charts": [{"type": "bar"}, {"type": "bubble"}, {"type": "table"}]
        },
        {
            "id": "gender",
            "label": "Gender",
            "description": null,
            "aggregations": [],
            "charts": [{"type": "bar"}, {"type": "bubble"}, {"type": "table"}]
        },
        {
            "id": "value",
            "label": "Value",
            "description": null,
            "aggregations": [{"type": "sum"}, {"type": "mean"}, {"type": "min"}, {"type": "max"}],
            "charts": []
        }

    ],
    "visualisations": [
        {
            "id": "1",
            "label": "Mortality in England and Wales",
            "description": "Explore and compare the number of deaths by disease, sex, area and year",
            "provenance": "Mortality statistics are based on details collected when deaths are certified and registered",
            "public": true,
            "elements": [
                {
                    "id": "year",
                    "label": "Year",
                    "measure_label": "Number of deaths",
                    "type": "bar",
                    "aggregation": "sum",
                    "measure": {"id": "value"},
                    "dimensions": [{"field": {"id": "year", "type": "string"}}],
                    "width": 1,
                    "weight": 2,
                    "display": true
                },
                {
                    "id": "gender",
                    "label": "Gender",
                    "measure_label": "Number of deaths",
                    "type": "bar",
                    "aggregation": "sum",
                    "measure": {"id": "value"},
                    "dimensions": [{"field": {"id": "gender", "type": "string"}}],
                    "width": 1,
                    "weight": 5,
                    "display": true
                }
            ],
            "styles": []
        }
    ],
    "modified": "2013-09-06T10:33:39.789859",
    "created": "2013-09-06T10:33:39.789859"
}

Create

Request
curl -XPOST -u'dataseed@example.com:password' -H'Accept: application/json' -H'Content-type: application/json' http://dataseedapp.com/api/datasets/
{
    "label": "My Vehicle Dataset",
    "public": false,
    "fields": [
        {
            "id": "vehicle",
            "label": "Vehicle",
            "description": null,
            "aggregations": [],
            "charts": [{"type": "bar"}, {"type": "bubble"}, {"type": "table"}]
        },
        {
            "id": "miles",
            "label": "Miles",
            "description": null,
            "aggregations": [{"type": "sum"}, {"type": "mean"}, {"type": "min"}, {"type": "max"}],
            "charts": []
        }
    ]
}
Response
{
    "status": 303,
    "href": "/api/datasets/252b529188c2bdee4c16570a133a329d"
}

Update

By making a PUT request to the URL returned in the previous call we can make changes to our new dataset.

Request
curl -XPUT -u'dataseed@example.com:password' -H'Accept: application/json' -H'Content-type: application/json' http://dataseedapp.com/api/datasets/252b529188c2bdee4c16570a133a329d
{
    "label": "My Awesome Vehicle Dataset",
    "public": false
}
Response
{
    "status": 303,
    "href": "/api/datasets/252b529188c2bdee4c16570a133a329d"
}

Delete

Request
curl -XDELETE -u'dataseed@example.com:password' -H'Accept: application/json' http://dataseedapp.com/api/datasets/252b529188c2bdee4c16570a133a329d
Response
{
    "status": 200,
    "message": "Deleted"
}

Dimensions

Read

Request
curl -H'Accept: application/json' http://dataseedapp.com/api/datasets/mortality/dimensions/gender
Response
{
    "gender": {
        "F": {
            "id": "F",
            "label": "Female"
        },
        "M": {
            "id": "M",
            "label": "Male"
        }
    }
}

Create

Creating (POSTing) dimension values will delete any existing dimension values. To append dimension values use PUT.

Request
curl -XPOST -u'dataseed@example.com:password' -H'Accept: application/json' -H'Content-type: application/json' http://dataseedapp.com/api/datasets/mortality/dimensions/gender
{
    "gender": {
        "F": {
            "id": "F",
            "label": "Female"
        },
        "M": {
            "id": "M",
            "label": "Male"
        }
    }
}
Response
{
    "status": 200,
    "message": "Created"
}

Update

Request
curl -XPUT -u'dataseed@example.com:password' -H'Accept: application/json' -H'Content-type: application/json' http://dataseedapp.com/api/datasets/mortality/dimensions/gender
{
    "gender": {
        "F": {
            "id": "F",
            "label": "Female"
        }
    }
}
Response
{
    "status": 200,
    "message": "Updated"
}

Delete

Request
curl -XDELETE -u'dataseed@example.com:password' -H'Accept: application/json' http://dataseedapp.com/api/datasets/mortality/dimensions/gender
Response
{
    "status": 200,
    "message": "Deleted"
}

Observations

Read

When requesting observations they are returned aggregated on a particular measure for a particular dimension. The dimension is specified in the URL and the measure with the following GET parameters:

In the example below we are requesting a "sum" aggregation of the "value" measure for the "gender" dimension.

Request
curl -H'Accept: application/json' http://dataseedapp.com/api/datasets/mortality/observations/gender?aggregation=sum&measure=value
Response
{
    "gender": [
        {
            "id": "F",
            "total": 2645375.0
        },
        {
            "id": "M",
            "total": 2412236.0
        }
    ]
}

Create

Creating (POSTing) observations will delete any existing entries. To append observations use PUT.

Request
curl -XPOST -u'dataseed@example.com:password' -H'Accept: application/json' -H'Content-type: application/json' http://dataseedapp.com/api/datasets/mortality/observations
{
    "observations": [
        {
            "gender": "M",
            "year": 2008,
            "chapter": "IX",
            "value": 12
        },
        {
            "gender": "F",
            "year": 2008,
            "chapter": "IX",
            "value": 18
        }
    ]
}
Response
{
    "status": 200,
    "message": "Created"
}

Update

Request
curl -XPUT -u'dataseed@example.com:password' -H'Accept: application/json' -H'Content-type: application/json' http://dataseedapp.com/api/datasets/mortality/observations
{
    "observations": [
        {
            "gender": "F",
            "year": 2004,
            "chapter": "V",
            "value": 9
        },
        {
            "gender": "F",
            "year": 2004,
            "chapter": "IV",
            "value": 31
        }
    ]
}
Response
{
    "status": 200,
    "message": "Updated"
}

Delete

Request
curl -XDELETE -u'dataseed@example.com:password' -H'Accept: application/json' http://dataseedapp.com/api/datasets/mortality/observations
Response
{
    "status": 200,
    "message": "Deleted"
}

Get an invite!

Sign up now to be one of the first to participate in the dataseed beta launch