Creating a visualization · Flourish for developers

Note: the Flourish API is an enterprise-level bolt-on and not available to all customers.

Interactive example

An interactive example can be found on JSFiddle. You will need to drop in your API key where the code is expecting it in order to make this example work.

Initialization & options

To create a visualization, use an initialization like so:

var flourish_visualization = new Flourish.Live(opts);

where opts is an object that contains the template settings and data that you want to use. The object should contain the following properties:

Property	type	Description
`template`	string	The user and ID of the template in format `@username/id` (e.g. `@flourish/scatter`)
`version`	string	The version number of the template (e.g. `4.4.0`). The version number can be found on the template showcase page, e.g. https://app.flourish.studio/@flourish/scatter
`container`	string or node	The target element in your HTML to load the visualization in. If it’s a string, it’s treated as a CSS selector (for example, `#chart` or `body`)
`api_key`	string	Your API key
`data`	object	Your data. See the “How to add data” section below for details.
`metadata`	object	Information about data types. See the "How to add metadata" section below for details.
`bindings`	object	An object containing the template's data bindings and which properties in your dataset to use. See the “How to add data” section below for details.
`state`	object	Settings to customize the visualization. See the “How to customize the visualization” section below for details.
`width`	string or number	Width of embed, as a number of pixels or a string in CSS syntax. Optional, and defaults to 100% if omitted.
`height`	string or number	Optional, and should usually be omitted. The default behavior, if height is omitted, is for the height to adjust as appropriate for the data being visualized. You can specify this option if you need the embed to have a fixed height that will not change in response to the visualization.

For example:

var opts = {
    template: "@flourish/scatter",
    version: "4",
    container: "#chart",
    api_key: "<api-key>",
    bindings: {
        data: {
            x: "pos_x",
            y: "pos_y",
            metadata: ["country"]
        }
    },
    data: {
        data: [
            { country: "Argentina", pos_x: 1, pos_y: 2 },
            { country: "Brazil", pos_x: 2, pos_y: 4 },
            { country: "Colombia", pos_x: 3, pos_y: 9 },
        ]
    },
    state: {
        layout: {
            title: "This is an API Example"
        }
    }
};

How to add data

To add data to the visualization, there are two things you need to do:

1. Add your data to the data property

The data property contains an object with the name of the template's dataset and an array of data. The template's datasets are different for each template. Most templates have only 1 dataset which is called "data", but some templates have more datasets (which basically means they have multiple datasheets) that could be named differently.

2. Select which columns you want to visualize, using the bindings property

Each template has a series of data bindings that describe what each column of the data should be used for. In the bindings property you specify an object that tells the visualization which column names in your dataset to use for each data binding.

You can provide your data in one of two different formats; either as an array-of-objects, or an array-of-arrays. Let's look at an example of each format. Imagine you wanted to visualize some data in a simple scatter plot. The scatter plot template has two data bindings called x and y, which respectively are used to set the horizontal and vertical position of a dot. There is another data binding called metadata that is being used to display information in a popup when hovering over a dot, which can contain multiple columns.

Array-of-objects format

In the array-of-objects format, each point in your scatter plot would be represented by an object. The object's keys would play the same role as the column headers in a Flourish datasheet:

var opts = {
    ...
    data: {
        // The dataset with the name data is an array-of-objects
        data: [
            {
                pos_x: 34,
                pos_y: 20,
                country: "Argentina"
            },
            {
                pos_x: 10,
                pos_y: 80,
                country: "Brazil"
            }
        ]
    }
    ...
}

We want the pos_x field in the data to be used to bound to the x binding, the pos_y field to be bound to the y binding, and the country field to be bound to metadata, so the country information appears in the popup. So your bindings property would look like this:

var opts = {
    ...
    bindings: {
        data: {
            x: "pos_x",
            y: "pos_y",
            metadata: ["country"]
        }
    }
    ...
}

Array-of-arrays format

In the array-of-arrays format, each point in your scatter plot would be represented by an array, with the first row of the array containing the column headers:

var opts = {
    ...
    data: {
        // The dataset with the name data is an array-of-arrays
        data: [
            ["pos_x", "pos_y", "country"],
            [34, 20, "Argentina"],
            [10, 80, "Brazil"]
        ]
    }
    ...
}

When using the array-of-arrays format, instead of binding to a particular key within the objects, we bind to an index in the array. So the x binding would have values at index 0 bound to it, the y binding would have values at index 1 bound to it, and values at index 2 would be bound to the metadata binding:

var opts = {
    ...
    bindings: {
        data: {
            x: 0,
            y: 1,
            metadata: [2]
        }
    }
    ...
}

To find the data structure and binding names expected by each template, look on the template's showcase page. These showcase pages are found by clicking on the name of a template from the template chooser. There is an API documentation section at the bottom that documents the data structure required (as well as all the templates possible settings):

Find API documentation on template showcase pages

How to customize the visualization

In the app, each template has dozens of settings that you can tweak to customize your final visualization. You can customize your visualization in the same way using the API by changing the settings property. That property takes an object with all the settings for each template and their values.

For example, if you want to change the opacity of the dots in the scatter plot, you can use the setting fill_opacity, as documented on the template showcase page. The following code will set the opacity of the dots to 1.

var opts = {
    template: "@flourish/scatter",
    ...
    ...
    state: {
        fill_opacity: 1
    }
}

To find all the possible settings available in a template, go to the template showcase page and click API docs. To get to the showcase page, either click on the template's name on the template chooser, or use the following URL structure: https://app.flourish.studio/@flourish/TEMPLATE-NAME/latest.

Template API documentation

How to update the visualization

If your data or settings change, you will want to update the visualization. You can do this by calling update(opts) on the visualization API object with the new options. If you just want to change a setting, while keeping the same data (or vice versa), you can set opts.data = null (or opts.state = null).

For example, to change the opacity of the dots again:

var visualization_api = new Flourish.Live(opts);

document.querySelector("button").addEventListener("click", function() {
    opts.state.fill_opacity = Math.random();
    visualization_api.update(opts);
})

Accessing the full current state of the visualization

The getState() method of the visualization object allows you to access the full current state of the template, including any state changes resulting from user interaction, e.g. clicking on a menu item or zooming/panning a map.

(Anything that can be preserved in a story slide in the Flourish editor necessarily resides in the state and can be accessed this way.)

The method is asynchronous and takes a callback which is called passing in error and state, e.g.:

var visualization_api = new Flourish.Live(opts);

visualization_api.getState(function(error, state) {
    if (error) {
        console.error(error);
        return;
    }

    console.log(state);
});

How to generate an image of your visualization

You can generate a bitmap or SVG image of a visualization you've created with the Live API using the snapshot method of the Live API object. For example:

var visualization_api = new Flourish.Live(opts);

var snapshot_options = {
    download: true,
    format: "png",
}

var visualization_api.snapshot(snapshot_options, function (error, data) {
    if (error) {
        console.error(error);
        return;
    }
});

That will trigger a download of a PNG file called Flourish API Image.png. You can override the filename by adding:

    filename: "my-amazing-viz"

The format option must be one of:

"png" (default)
"jpeg"
"svg"

You can supply a scale parameter (default: 1) to increase the resolution of the generated image. For example, if you add:

    scale: 2

The download image will be double the size.

Images using a PNG or SVG format can be downloaded with transparent backgrounds by supplying a transparent-background parameter. To do this, you can add:

    transparent-background: true

Ensure your visualization has no background color or image provided in your state configuration by using:

    layout: {
        background_color_enabled: false
    }

If using a base visualization, turn the background color off in the layout settings.

Sometimes you might want the image data to use programmatically, rather than just triggering a file download. In that case, you can use the option download: false, and the image data will be passed in the callback as a data URL with base64-encoded data. This makes it easy to use that data as, say, the src attribute of an <img> tag.

For example:

var visualization_api = new Flourish.Live(opts);

var snapshot_options = {
    download: false,
    format: "jpg",
}

var visualization_api.snapshot(snapshot_options, function (error, data) {
    if (error) {
        console.error(error);
        return;
    }

    console.log(data.data); // "data:image/jpeg;base64,..."
});

How to add metadata

Note: Not all templates support metadata. You can find out if a particular version of a template supports metadata in the 'API Documentation' section on the template help pages.

Some templates support an optional metadata property. metadata informs the template what type of data is in each of your columns, and how that data should be formatted visually:

var opts = {
    template: "@flourish/scatter",
    ...
    data: {
        data: [
            { pos_x: 1, pos_y: 2, country: "Argentina", date: "31/01/1992" },
        ]
    },
    metadata: {
        date: {
            {
                type: "datetime",
                type_id: "datetime$%d/%m/%Y",
                output_format_id: "datetime$%m/%d/%Y",
            }
        }
    }
    ...
};

In the above example:

type: datetime indicates that the values in the date column are dates
type_id: "datetime$%d/%m/%Y", indicates that the dates are in DD/MM/YYYY format
output_format_id: "datetime$%m/%d/%Y" indicates that the dates should be displayed in MM/DD/YYYY format

In other words, the purpose of specifying opts.metadata is to override the default formatting of your data. However, if you don't need to format the values in any of your columns, it is also fine to omit opts.metadata (in which case Flourish will guess the types):

var opts = {
    template: "@flourish/scatter",
    ...
    data: {
        data: [
            { pos_x: 1, pos_y: 2, country: "Argentina", date: "31/01/1992" },
        ]
    },
    ...
};

You can specify metadata in one of two formats, depending on the format of opts.data.

1. Array of objects with column indexes as keys

When data is in the array-of-arrays format, metadata should be an object with column_index: column_type_object key/value pairs:

var opts = {
    template: "@flourish/scatter",
    ...
    data: {
        data: [
            [ "pos_x", "pos_y", "country", "date" ],
            [ 1, 2, "Argentina", "31/01/1992" ]
        ]
    },
    metadata: {
        data: {
            0: {
                type: "number",
                type_id: "number$comma_point",
                output_format_id: "number$comma_space",
            },
            1: {
                type: "number",
                type_id: "number$comma_point",
                output_format_id: "number$comma_space",
            },
            2: {
                type: "string",
                type_id: "string$arbitrary_string",
                output_format_id: "string$arbitrary_string",
            },
            3: {
                type: "datetime",
                type_id: "datetime$%d/%m/%Y",
                output_format_id: "datetime$%d/%m/%Y",
            }
        }
    }
    ...
};

2. Array of objects with column headers as keys

When data is in the array-of-objects format, metadata should be an object with column_header: column_type_object key/value pairs:

var opts = {
    template: "@flourish/scatter",
    ...
    data: {
        data: [
            { pos_x: 1, pos_y: 2, country: "Argentina", date: "31/01/1992" },
        ]
    },
    metadata: {
        data: {
            pos_x: {
                type: "number",
                type_id: "number$comma_point",
                output_format_id: "number$comma_space",
            },
            pos_y: {
                type: "number",
                type_id: "number$comma_point",
                output_format_id: "number$comma_space",
            },
            country: {
                type: "string",
                type_id: "string$arbitrary_string",
                output_format_id: "string$arbitrary_string",
            },
            date: {
                type: "datetime",
                type_id: "datetime$%d/%m/%Y",
                output_format_id: "datetime$%d/%m/%Y",
            }
        }
    }
    ...
};

Column type objects

Column type objects tell the API what type of data is in a column, and how to format it:

{
type: "number", // can also be 'string', or 'datetime'
type_id: "number$comma_point", // numbers in the format 13,429.17
output_format_id: "number$space_comma", // numbers in the format 13 429,17
}

type identifies whether the column contains string, number, or datetime data
type_id identifies the existing format of your data
output_format_id identifies how the data should be formatted when it is displayed in your visualization

See the Tables of Recognised Type Formats below for descriptions of valid type, type_id, and output_format_id values.

Recognised Data Types and Type Formats

In templates that support metadata, you can set the type for any column to be any of the following:

string
number
datetime

Currently supported formats for each type are listed by their type_id/output_format_id in the tables below:

String column IDs

`type_id`/`output_format_id`	Format	Examples
`string$arbitrary_string`	Text of any length	`It's a close race...`, `Results will be announced on 3 November`

Number columns IDs

`type_id`/`output_format_id`	Format	Examples
`number$comma_point`	Comma thousands separator, point decimal separator	`12,235.56`, `6,072.1`
`number$space_point`	Space thousands separator, point decimal separator	`12 235.56`, `6 072.1`
`number$none_point`	No thousands separator, point decimal separator	`12235.56`, `6072.1`
`number$point_comma`	Point thousands separator, comma decimal separator	`12.235,56`, `6.072,1`
`number$space_comma`	Space thousands separator, comma decimal separator	`12 235,56`, `6 072,1`
`number$none_comma`	No thousands separator, comma decimal separator	`12235,56`, `6072,1`

Date/time columns IDs

`type_id`/`output_format_id`	Format	Examples
`datetime$%Y-%m-%dT%H:%M:%S.%LZ`	YYYY-MM-DDTHH:MM:SS.sss (ISO 8601 UTC date & time)	`1972-04-27T10:10:10.303Z`, `2021-10-13T18:04:31.692Z`
`datetime$%d/%m/%Y`	DD/MM/YYYY	`27/04/1972`, `13/10/2021`
`datetime$%d/%m/%y`	DD/MM/YY	`27/04/72`, `13/10/21`
`datetime$%m/%d/%Y`	MM/DD/YYYY	`04/27/1972`, `10/13/2021`
`datetime$%m/%d/%y`	MM/DD/YY	`04/27/72`, `10/13/21`
`datetime$%Y/%m/%d`	YYYY/MM/DD	`1972/04/27`, `2021/10/13`
`datetime$%d-%m-%Y`	DD-MM-YYYY	`27-04-1972`, `13-10-2021`
`datetime$%d-%m-%y`	DD-MM-YY	`27-04-72`, `13-10-21`
`datetime$%m-%d-%Y`	MM-DD-YYYY	`04-27-1972`, `10-13-2021`
`datetime$%m-%d-%y`	MM-DD-YY	`04-27-72`, `10-13-21`
`datetime$%Y-%m-%d`	YYYY-MM-DD	`1972-04-27`, `2021-10-13`
`datetime$%d %b %Y`	DD Mon YYYY	`27 Apr 1972`, `13 Oct 2021`
`datetime$%d %B %Y`	DD Month YYYY	`27 April 1972`, `13 October 2021`
`datetime$%d %b %y`	DD Mon YY	`27 Apr 72`, `13 Oct 21`
`datetime$%d %B %y`	DD Month YY	`27 April 72`, `13 October 21`
`datetime$%d-%b-%Y`	DD-Mon-YYYY	`27-Apr-1972`, `13-Oct-2021`
`datetime$%d-%B-%Y`	DD-Month-YYYY	`27-April-1972`, `13-October-2021`
`datetime$%d-%b-%y`	DD-Mon-YY	`27-Apr-72`, `13-Oct-21`
`datetime$%d-%B-%y`	DD-Month-YY	`27-April-72`, `13-October-21`
`datetime$%m/%Y`	MM/YYYY	`04/1972`, `10/2021`
`datetime$%m/%y`	MM/YY	`04/72`, `10/21`
`datetime$%b %Y`	MM YY	`Apr 1972`, `Oct 2021`
`datetime$%B %Y`	MM YY	`April 1972`, `October 2021`
`datetime$%b %y`	MM YY	`Apr 72`, `Oct 21`
`datetime$%B %y`	MM YY	`April 72`, `October 21`
`datetime$%d %b`	DD Mon	`27 Apr`, `13 Oct`
`datetime$%d %B`	DD Month	`27 April`, `13 October`
`datetime$%b %d`	Mon DD	`Apr 27`, `Oct 13`
`datetime$%B %d`	Month DD	`April 27`, `October 13`
`datetime$%d-%m`	DD-MM	`27-04`, `13-10`
`datetime$%m-%d`	MM-DD	`04-27`, `10-13`
`datetime$%d/%m`	DD/MM	`27/04`, `13/10`
`datetime$%m/%d`	MM/DD	`04/27`, `10/13`
`datetime$%Y`	YYYY	`1972`, `2021`
`datetime$%B`	Month	`April`, `October`
`datetime$%b`	Mon	`Apr`, `Oct`
`datetime$%X`	H:MM:SS xM (12-hour)	`7:45:05 PM`, `9:01:58 AM`
`datetime$%I:%M %p`	HH:MM xM (12-hour)	`07:45 PM`, `09:01 AM`
`datetime$%H:%M`	HH:MM (24-hour)	`19:45`, `09:01`
`datetime$%H:%M:%S`	HH:MM:SS (24-hour)	`19:45:05`, `09:01:58`
`datetime$%-I%p`	HxM (12-hour)	`7PM`, `9AM`
`datetime$Q%q %Y`	Qn YYYY	`Q2 1972`, `Q4 2021`