User guide

Getting started

Grafl currently has a single API endpoint that can be used for both GET requests and POST data. The Grafl API endpoint is available at https://grafl.io/api/

Plots can be generated via GET or POST requests by making a simple API call, passing data and parameters using as JSON. The form of the data is similar to format of Plotly’s parameters for traces and layouts (https://plotly.com/python/reference/), with a number of modifications to reduce some duplication and simplify the mixing of plot types.

GET requests

The basic form of API request using a GET parameter for the following plot data can be seen below:

https://grafl.io/api/?g={"figure":{"plots":[{"base":{"type":"bar","x":["Trains","Planes","Automobiles"]},"traces":[{"data":{"name":"Bob","y":[20,4,32]}},{"data":{"name":"Jane","y":[14,9,29]}}]}],"layout":{"showlegend":true,"title_text":"Holiday travel","title_x":0.5,"xaxis_title":"Modes of transport","yaxis_title":"Count"}}}

The length of GET request paramaters may be limited by the browser, and therefore should be used for simpler plots with less data points. For more complex plots with more data points, a POST should be used.

Grafl can also render a plot into an iframe by using the src attribute:

<iframe title='Grafl GET request to iframe'
    src='https://grafl.io/api/?g={"figure":{"plots":[{"base":{"type":"bar","x":["Trains","Planes","Automobiles"]},"traces":[{"data":{"name":"Bob","y":[20,4,32]}},{"data":{"name":"Jane","y":[14,9,29]}}]}],"layout":{"showlegend":true,"title_text":"Holiday travel","title_x":0.5,"xaxis_title":"Modes of transport","yaxis_title":"Count"}}}'
    frameBorder='0'
    width='100%'
    height='600'
    style='background-color:#FFFFFF;'>
  </iframe>

POST data

Sometimes you may have more data than can be included in GET parameters. In that case JavaScript can be used to POST data to Grafl and render the response to an iframe. The callGrafl script below shows one way of doing this using an XMLHttpRequest.

Example XMLHttpRequest for sending data to Grafl:

<div id="grafl-container"></div>

<script>
      function callGrafl() {
          const data = '{"figure":{"plots":[{"base":{"type":"bar","x":["Trains","Planes","Automobiles"]},"traces":[{"data":{"name":"Bob","y":[20,4,32]}},{"data":{"name":"Jane","y":[14,9,29]}}]}],"layout":{"showlegend":true,"title_text":"<b>Post</b> data to <b>Grafl</b> and render<br>the response to an <b>iframe</b>","title_x":0.5,"xaxis_title":"Modes of transport","yaxis_title":"Count"}}}';
          const container = document.getElementById('grafl-container');
          const xhr = new XMLHttpRequest();

          xhr.open('POST', "https://grafl.io/api/");
          xhr.setRequestHeader('Content-Type', 'application/json;charset=UTF-8');
          xhr.onreadystatechange = function() {
              if (xhr.readyState == 4 && xhr.status === 200) {
                  // Create iframe to hold the plot
                  container.innerHTML = '<iframe title="Grafl plot" src="about:blank" frameBorder="0" width="100%" height="500" style="background: #FFFFFF;"></iframe>';

                  // Write the response to the iframe
                  const iframe = container.children[0];
                  iframe.contentWindow.document.open();
                  iframe.contentWindow.document.write(xhr.responseText);
                  iframe.contentWindow.document.close();
              }
          }
          xhr.send(data);
      }
</script>

Basic data structure

Plot data is structured in a hierarchy starting with the main top level figure object.

"figure": {
    "plots": [{
        "traces": [{
            "data": {
                ...
            }
        }]
    }]
}

Name	Value	Required	Description
figure	object	yes	Top level plot object
format	object	no	Plot output format. animated HTML (default), standard HTML, SVG, PNG
config	object	no	Plot config format

Figure

figure is a top level object encapsulating the following parameters:

Name	Value	Required	Description
plots	array of plot objects	yes
subplots	object	no
layout	object	no	Plotly reference
update_traces	object	no
update_xaxes	object	no	Plotly reference
update_yaxes	object	no	Plotly reference
update_annotations	object	no
update_geos	object	no

Plots

Name	Value	Required	Description
base	object	no	Base plot structure for factoring out commonality between plots, to reduce duplication.
traces	array of trace objects	yes

Traces

Name	Value	Required	Description
data	object	yes
row	number	no	Used for creating subplots
col	number	no	Used for creating subplots

Base

Common plot parameters and values such as type, x, y etc.

Data

Plot specific parameters and values such as type, x, y etc.

Format

format is an optional top level object encapsulating the following parameters:

Name	Value	Required	Description
format_type	string	no	standard (default), animated (experimental use only), svg, png
width	number	no
height	number	no
img_tag	boolean	no	used to wrap png format images in an img tag. Default is false
credit	object	no	set the position and style of the plot credit label Made with Grafl.io

Credit

credit is an optional object encapsulating the following parameters:

Name	Value	Required	Description
type	string	no	label background style, light (default) or dark
x	number (0-1)	no	x placement of label in plot space
y	number (0-1)	no	y placement of label in plot space

Default is x=1, y=0 which places the credit label in the bottom left corner of the plot.

Config

config is an optional top level object encapsulating the following parameters:

Name	Value	Required	Description
displayModeBar	boolean	no
displaylogo	boolean	no

Grouping parameters

Parameters can be separated by underscores or can be grouped. This can be a useful way of reducing the size of the Grafl data structure. The following two structures are equivalent:

{"title_text": "Holiday travel", "title_x": 0.5, "title_y": 1}

"title": {"text": "Holiday travel", "x": 0.5, "y": 1}

Colors

Colors in plots can be represented using the following:

• CSS color names: ["red", "green", "blue"]
• RGB colors: ["rgb(255,0,0)", "rgb(0,255,0)", "rgb(0,0,255)"]
• RGBA colors: ["rgba(255,0,0,1)", "rgba(0,255,0,1)", "rgba(0,0,255,1)"]
• HEX colors: ["#FF0000", "#00FF00", "#0000FF"]

Escaping HEX colors

If HEX colors are used in GET request parameters, they need to be escaped to %23. For example, if the following colors ["#4682B4", "#B4464B", "#B4AF46"] are sent in a GET request, they must be escaped to ["%234682B4", "%23B4464B", "%23B4AF46"].

HEX colors in POST data do not need to be escaped.