API Tutorial

How to create an interactive data analytic map with the Datamatic API

In the past creating an interactive data visualization could be a hard, and often time consuming task. On the web you can find numerous examples of people creating awesome data visualizations, which could take weeks, or even months to produce. With the explosive growth of data, there is a need to quickly build complex visualization in a couple of days, hours, or even minutes. In the tutorial below, we will show you how you can use DataMatic to produce a stunning visualization in under an hour.

This visualization will show the average price in all the inner London districts between the years 1995 and 2015, using Datamatic as the chart render, Briskat for the data API,  dat.GUI for the UI controls and JSFiddle to host this example.


Demo: http://jsfiddle.net/jarben/kbphv1pb/


  • Go to the DataMatic website, and sign up the free plan.
  • Once you are in the editor, choose the “Map” chart and click OK


Your graph should look like the following:

The London map is not part of our sample charts, so we need to find an external London GEO JSON and use it in the map-type property. We are going to use a map hosted on GitHub:


We can now delete the US data and add some dummy data to test our chart.

This is pretty much all we need to do to start with, so we can now publish this chart which will give you sample Javascript code in the API section:



JS Fiddle

Go the JS Fiddle website, paste this code into HTML section and run the following code:

We would suggest you move all the javascript code into the JS editor and move the script tags into JSFiddle resources:


The data API for this example was kindly provided by Briskat. Their super-fast analytical database is capable of near-instant response times which give us almost client-side feel for most of the queries, checkout Briskat’s website to learn more. We’re going set data from their API endpoint:

Datamatic.ajax.json("http://house.briskat.com/api/p/lruk/r/area", {
    yr: 2015, // year
    dim: "pcdistrict", // set post code level to disctrict
    pc: 1 // 1=inner London area
}).then(function(data) {
    chart.setData(data.map(function (item) {
        return {
            name: item[0],
            value: item[2]

Which gives us real data on the map and allows users to filter areas using the min/max data range component:

Let’s move back to the visual editor and set some properties such as:

  • theme to ‘roma’
  • title, link text & styling
  • enable tooltip
  • customize data range to be positioned on the left etc.

You should see something like this:

When you publish and run your JSFiddle example again, you should see the following map:

The next stage is to add some controls. We’re going to use dat.GUI lightweight controller for that, but you can choose any other widgets or simple HTML elements.

  • Add https://cdnjs.cloudflare.com/ajax/libs/dat-gui/0.5/dat.gui.min.js to your external resources:


  • Create a simple year control
// create control panel
var gui = new dat.GUI();

// options data model
var options = {
    year: 2015
// add year range
var yearControl = gui.add(options, 'year', 1995, 2015);

// update data when yearControl changes

Replace parameter value in the request:

yr:2015 // year


yr: parseInt(options.year), // year

Now, you should have a map where changing the year option triggers a http request and updates the map:

The following function will make it easier to add new options and also add a bit of optimization to the controls:

function addController() {
    var controller = gui.add.apply(gui, arguments);
    var delayedTask = Datamatic.utils.delayTask(updateData);

    controller.onChange(function () {
        // wait 50ms before updating the map, this prevents large number of request if user moves sliders

The data API result format is: [post_code, num_of_properties, average_price, year_over_year]. We can also add another option to the control panel which changes a metric shown in the map:

addController(options, 'metric', {
    "Num of properties": 1,
    "Average Price": 2,
    "Year over year": 3

and use this option when setting data:

var metric = options.metric;
chart.setData(data.map(function (item) {
    return {
        name: item[0],
        value: item[metric]

From our last change here are the results: