Creating a visualization
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):
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
.
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 visualisation
You can generate a bitmap or SVG image of a visualisation 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.
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.result); // "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 thedate
column are datestype_id: "datetime$%d/%m/%Y",
indicates that the dates are in DD/MM/YYYY formatoutput_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 containsstring
,number
, ordatetime
datatype_id
identifies the existing format of your dataoutput_format_id
identifies how the data should be formatted when it is displayed in your visualisation
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 |