Format

Chart config is stored in a JSON object, broken down in to nested objects for the various components of the chart. The chart config can be stored in the REST API, or used to generate interactive charts or images on the fly.

Parameter types

String Accepts a string, unless a set of valid values are specified.
Integer i.e. 1, 4, 500
Float i.e. 1, 1.0, 50.3
Boolean i.e. true, false, 1, 0
Color Accepts a hex, rgb or rgba string unless otherwise stated. i.e. #ffffff, rgb(255, 255, 255) or rgba(255, 255, 255, 0.5)

If a parameter type is followed by square brackets (i.e. Color[]) it implies you can send an array of that parameter type (e.g. [‘#000000’, ‘#ffffff’])

Config object

Top level

Config structure

Parameter Type Description
type String

Width of chart canvas in pixels

Valid values: bar, line, area, pie

canvas Object

See Canvas
series Object

See Series
axes Object

See Axes
meta Object

See Meta
options Object

See Options
legend Object

See Legend
tooltip Object

See Tooltip
color Object

See Color

Examples

A typical chart config root would look like this

            
            {
    "type": "bar",
    "canvas": {},
    "series": {}
}

Canvas

Control size and style of the chart canvas

Parameter Type Description
canvas Object

Canvas root
canvas.width Integer

Width of chart canvas in pixels

Default: 800

canvas.height Integer

Height of chart canvas in pixels

Default: 400

canvas.margin Object

Spacing from edge of canvas to start of chart
canvas.margin.top Integer

In pixels

Default: 20

canvas.margin.right Integer

In pixels

Default: 20

canvas.margin.bottom Integer

In pixels

Default: 20

canvas.margin.left Integer

In pixels

Default: 20

canvas.background-type String

Style of background

Default: solid

Valid values: solid, gradient, transparent

canvas.background-color Color

Hex, rgb or rgba color

Default: #000000

canvas.gradient Object

Background gradient options
canvas.gradient.colors Color[]

Array of hex or rgb colors to create a gradient with
canvas.gradient.direction String

Direction of the gradient

Valid values: top, bottom, left, right

canvas.font-family String

Default font to use across chart

Default: Arial

canvas.font-size Integer

Default font size to use across chart

Default: 10

canvas.font-color Color

Default font color to use across chart

Default: #000000

Examples

An example of a full canvas object

            
            {
    "canvas": {
        "width": 800,
        "height": 400,
        "margin": {
            "top": 20,
            "right": 20,
            "bottom": 20,
            "left": 20
        },
        "background-type": "solid",
        "background-color": "#ffffff",
        "font-family": "Arial",
        "font-size": 10,
        "font-color": "#000000"
    }
}

Series

Each series represents a line/bar/area, depending on the type of chart being rendered

Parameter Type Description
series Object

Series root
series.[id] String

Each series must have a unique ID assigned to it, as the object key. Valid characters are A-Z0-9_
series.[id].show Boolean

Whether to draw the series on the chart

Default: true

series.[id].title String

The name of the series (appears in Legend)
series.[id].color Color[]

A single color or array of colours applied to the bar/line/area
series.[id].order Integer

The order to display/render the series in
series.[id].source Object

Contains information on how to obtain data for this series
series.[id].source.type String

Location of the data

Default: dataset

Valid values: dataset

series.[id].source.setId String

ID of the dataset to source the data from
series.[id].source.direction String

Whether to iterate over the sets rows or columns

Default: columns

Valid values: rows, columns

series.[id].source.headersFirst Boolean

Whether to treat the first row as axis headings
series.[id].source.x Integer[]

Column(s) that make up the x value
series.[id].source.groupBy Integer[]

Column(s) that should be grouped by matching values
series.[id].source.groupAccumulator String

How to manipulate grouped values

Valid values: avg, sum, count, max, min, first, last

series.[id].source.y Integer[]

Column(s) that make up the y value
series.[id].source.from Integer

Which row/column to start sourcing the data from

Default: 1

series.[id].source.to Integer

Which row/column to source the data to
series.[id].source.limit Integer

Maximum number of data points to use
series.[id].source.offset Integer

Offset this many rows/columns with range of data
series.[id].source.sortBy Integer[]

Row/column to sort data by
series.[id].source.order Integer

Ascending (1), Descending (-1) order

Default: 1

Valid values: 1, -1

Examples

An example of sourcing all data from column A (X) and B (Y) of a dataset

            
            {
    "series": {
        "example-0": {
            "show": true,
            "title": "Example data",
            "color": ["#F2C313"],
            "order": 0,
            "source": {
                "type": "dataset",
                "setId": "542713dcc9a61d5c0c8b4567",
                "direction": "columns",
                "headersFirst": true,
                "x": [1],
                "y": [2],
                "groupBy": [1],
                "groupAccumulator": "sum",
                "from": 1,
                "to": null,
                "limit": null,
                "offset": null,
                "sortBy": [],
                "order": 1
            }
        }
    }
}

Axes

Configuring the chart axes (typically X, Y and Y2)

Parameter Type Description
axes Object

Axes root
axes.[axis] String

The axis key to configure

Valid values: x, y, y2

axes.[axis].show Boolean

Whether to draw the axis on the chart

Default: true

axes.[axis].color Color

The color of the axis line
axes.[axis].thickness Integer

The thickness of the axis line in pixels

Default: 2

axes.[axis].position String

Where the axis should sit in relation to the chart

Valid values: left, bottom, top, right

axes.[axis].format String

How to format the axis ticks

Valid values: auto, text, percent, number-roundString, number-round2, date-YYYY-MM-DD, date-YYYY-MM-DD HH:mm, date-DD/MM/YYYY, date-DD/MM/YYYY HH:mm

axes.[axis].scale Object

Object for controlling the scale of the axis
axes.[axis].scale.type Object

Type of scale to apply

Default: auto

Valid values: auto, linear, log, ordinal

axes.[axis].scale.forceZero Boolean

Whether 0 should appear on the axis
axes.[axis].scale.niceValues Boolean

Whether the axis should round to nice values at the start and end

Default: true

axes.[axis].label Object

A label object, used to set the axis label that describes the axis
axes.[axis].label.show Boolean

Whether the label is visible
axes.[axis].label.value String

The text to display
axes.[axis].label.color Color

The text color
axes.[axis].label.font-family String

Font to use
axes.[axis].label.font-size Integer

Size of label
axes.[axis].label.rotate Integer

Number of degrees to rotate the label. Defaults to 0, 90 or 180 depending on the axis
axes.[axis].ticks Object

Tick object
axes.[axis].ticks.show Boolean

Whether to display ticks on the axis

Default: true

axes.[axis].ticks.quantity Integer

Maximum number of ticks to display along the axis
axes.[axis].ticks.color Color

Color of the tick text

Default: true

axes.[axis].ticks.font-family String

Font to use
axes.[axis].ticks.font-size Integer

Size of ticks
axes.[axis].ticks.rotate Integer

Number of degrees to rotate the ticks

Default: 0

axes.[axis].grid Object

Grid object
axes.[axis].grid.show Boolean

Whether to draw the grid lines
axes.[axis].grid.color Color

The color of the grid lines
axes.[axis].grid.thickness Integer

The thickness of the grid lines in pixels

Default: 1

Examples

An simple example of an X and Y axis

            
            {
    "axes": {
        "x": {
            "show": true,
            "position": "bottom",
            "thickness": 2,
            "color": "rgba(235, 233, 221, 0.3)",
            "label": {
                "show": true,
                "value": "X axis",
                "color": "rgb(235, 233, 221)",
                "font-size": 16,
                "font-family": "Arial",
                "rotate": 0
            },
            "ticks": {
                "show": true,
                "quantity": 5,
                "color": "rgb(235, 233, 221)",
                "font-family": "Arial",
                "font-size": 14,
                "rotate": 0
            },
            "grid": {
                "show": false,
                "thickness": 1,
                "color": "rgb(235, 233, 221)"
            }
        },
        "y": {
            "show": true,
            "position": "left",
            "thickness": 2,
            "color": "rgba(235, 233, 221, 0.3)",
            "format": "number-roundString",
            "scale": {
                "type": "log"
            },
            "label": {
                "show": true,
                "value": "Y axis",
                "color": "rgb(235, 233, 221)",
                "font-size": 16,
                "font-family": "Arial",
                "rotate": 270
            },
            "ticks": {
                "quantity": 6,
                "show": true,
                "rotate": 0,
                "font-family": "Arial",
                "font-size": 14,
                "color": "rgb(235, 233, 221)"
            },
            "grid": {
                "show": true,
                "thickness": 1,
                "color": "rgba(235, 233, 221, 0.3)"
            }
        }
    }
}

Meta

Information about the chart

Parameter Type Description
meta Object

Meta root
meta.title Object

Title object
meta.title.show Boolean

Show the title?

Default: true

meta.title.value String

The text value
meta.title.color Color

Color of title text
meta.title.font-family String

Font to use for text
meta.title.font-size Integer

Size of title text
meta.title.rotate Integer

Rotation of title text

Default: 0

meta.title.position Object

Position object
meta.title.position.type String

Where to put the title in the canvas

Default: top-left

Valid values: custom, top-left, top-center, top-right, center-left, center-right, bottom-left, bottom-center, bottom-right

meta.title.position.insideMargin Boolean

Calculation inside or outside the margin
meta.title.position.fitInCanvas Boolean

Check that the title sits within the canvas

Default: true

meta.title.position.coordinates Object

If the position type is ‘custom’, set the coordinates here
meta.title.position.coordinates.x Float

X coordinates from left

Default: 0

meta.title.position.coordinates.y Float

Y coordinates from top

Default: 0

meta.description Text

A description of the chart used for html meta etc

Examples

A title at the top left of the canvas

            
            {
    "meta": {
        "title": {
            "show": true,
            "value": "My chart",
            "font-family": "Arial",
            "font-size": "22",
            "color": "rgb(235, 233, 221)",
            "rotate": 0,
            "position": {
                "type": "top-left"
            }
        },
        "description": "This is a lovely chart example."
    }
}

Options

Type specific options

Parameter Type Description
options Object

Options root
options.area Object

Area object
options.area.show Boolean

Fill the area
options.border Object

Border object, used for pie slices
options.border.color Color

Color of the border (line)
options.border.thickness Integer

Thickness of the border in pixels

Default: 0

options.donut Integer

Size of hole in a pie chart

Default: 0

options.horizontal Boolean

Makes the bars in a column chart horizontal
options.interpolate String

Used to manipulate, normally smoothen, data

Default: linear

Valid values: linear, cardinal

options.lines Boolean

Whether to draw lines on line/scatter charts

Default: true

options.offset Integer

Where to start the first slice of a pie chart, in degrees

Default: 0

options.points Object

Points object
options.points.show Boolean

Whether to draw points on line/scatter charts
options.points.shape String

Shape of the point

Default: circle

Valid values: circle, square, cross, diamond, triangle-down, triangle-up

options.portion Integer

Completeness of pie chart, in degrees. Used to make election charts

Default: 0

options.stacked Boolean

Whether to stack bars/areas

Examples

A horizontal, stacked bar chart

            
            {
    "options": {
        "horizontal": true,
        "stacked": true
    }
}

The configuration to convert a pie chart in to an election chart

            
            {
    "options": {
        "donut": 60,
        "offset": 260,
        "portion": 200
    }
}

The configuration to display points on a line chart

            
            {
    "options": {
        "points": {
            "show": true,
            "shape": "circle"
        }
    }
}

Legend

Configuring a legend for the chart

Parameter Type Description
legend Object

Legend root
legend.show Boolean

Whether to show the legend
legend.style String

Style of the legend

Default: vertical

Valid values: horizontal, vertical

legend.shape String

Shape of each key element

Default: circle

Valid values: none, circle, cross, diamond, square, triangle-down, triangle-up, shape

legend.font-color Color

Color of series title text in legend
legend.font-family String

Font for series title text
legend.font-size Integer

Font size for series title text
legend.position Object

Position object
legend.position.type String

Where to put the title in the canvas

Default: top-left

Valid values: custom, top-left, top-center, top-right, center-left, center-right, bottom-left, bottom-center, bottom-right

legend.position.coordinates Object

If the position type is ‘custom’, set the coordinates here
legend.position.coordinates.x Float

X coordinates from left

Default: 0

legend.position.coordinates.y Float

Y coordinates from top

Default: 0

Examples

Displays a legend to the right of the chart

            
            {
    "legend": {
        "show": true,
        "style": "vertical",
        "shape": "circle",
        "font-color": "rgb(102, 102, 102)",
        "font-family": "Arial",
        "font-size": 14,
        "position": {
            "type": "top-right"
        }
    }
}

Tooltip

Configure tooltips on hover of the chart

Parameter Type Description
tooltip Object

Tooltip root
tooltip.show Boolean

Enable tooltips on chart

Examples

Tooltips enabled

            
            {
    "tooltip": {
        "show": true
    }
}

Color

A palette of colors to choose from when adding new series

Parameter Type Description
color Color[]

Palette colors

Examples

Can use a mix of color formats

            
            {
    "color": [
        "#ffffff",
        "#000000",
        "rgb(135,135,135)",
        "rgba(55, 55, 55, 0.5)"
    ]
}