API Quickstart

This document intends to describe high level features of the API. It is supplied as an add-on to the reference. You may find the reference is in disagreement with this document, in which case this document is to be preferred.

For more advanced use-cases, and to know what everviz itself sends to these endpoints, be sure to check out the forum article on reverse engineering the API if you want to know what everviz itself is sending to these endpoints.

To interact with the API, and X-API-Key HTTP header must be present with requests to https://api.everviz.com

To generate an API key to, read the page on API key settings.

A request to our API can then be made like so:

const request = async (method, path, body) => {
    const endpoint = 'https://api.everviz.com'
    const apiKey = <>

    const r = {
        method: method,
        headers: {
            'Content-Type': 'application/json',
            'X-API-Key': apiKey
        },
        body: body
    }
    const res = await fetch(endpoint + path, r)

    return (res.status === 200)
        ? await res.json()
        : console.error(endpoint + path, res.status, res.statusText, r)
}

Which we will use with some helpers:

const post = async (path, body) => request('post', path, body)
const get = async (path, body) => request('get', path, body)

A few endpoints require a team ID to work on, so we will define that here, as we don't intend to change it between calls.

const teamid = <Your team ID>

We should now have a base template that looks like so:

const teamid = ''

const request = async (method, path, body) => {
    const endpoint = 'https://api.everviz.com'
    const apiKey = ''

    const r = {
        method: method,
        headers: {
            'Content-Type': 'application/json',
            'X-API-Key': apiKey
        },
        body: body
    }
    const res = await fetch(endpoint + path, r)

    return (res.status === 200)
        ? await res.json()
        : console.error(endpoint + path, res.status, res.statusText, r)
}

const post = async (path, body) => request('post', path, body)
const get  = async (path, body) => request('get', path, body)

How-to

Step-by-step guides to help you achieve a specific goal. Useful if you need to get going quick.

How to create a chart

Using the below, you should reliably be able to create a Pie chart.

let data = {
    options: {
        chart: {
            type: 'pie'
        },
        title: {
            text: 'My chart'
        },
        data: {
            csv: '"Name","Value"\n"A",60\n"B",40',
            seriesMapping: [{
                x: 0,
                y: 1
            }],
        }
    },
    settings: {
    },
    theme: {
        id: <int>
    }
}

// Important for now.
data.settings.dataProvider = data.options.data


post(`/team/${teamid}/chart`, JSON.stringify({
    data: JSON.stringify(data),
    referenced: 0,
    name: 'My chart',
}))

How to modify a chart

This is currently a bit of a stretch, so we have written a helper to do most of the leg-work for you:

const patchChart = async (uuid) => {
    let chart = await getChart(uuid)
    chart.data = JSON.parse(chart.data)
    chart.details = JSON.parse(chart.details)

    // Connecting is necessary for now. `details` and `dataProvider` is the data connected to a chart.
    chart.data.settings.dataProvider = chart.details

    // Expects object matching https://api.highcharts.com/highcharts/
    const callback = async (options) => {
        chart.data.options = options
        return await post(`/team/${teamid}/chart/${chart.chart_id}`, JSON.stringify({
            data: chart.data,
        }))
    }

    return {
        // Object matching https://api.highcharts.com/highcharts/
        options: chart.data.options,
        callback: callback
    }
}

A few things are happening here, which is explained later, but most importantly you should know that everviz works on objects that contain a Highcharts configuration. This code is about making that available to you, and leaving the other stuff out. transformations, whilst letting you work on the well defined Highcharts configuration.

You can set any property on the object and return it to the callback. I like to use deep setters and getters, such as the ones provided by Lodash. This allows me to work with any nested property I like, without needing to check for it. So then we call our method like so:

const r = await patchChart(uuid)
r.options = _.set(r.options, 'title.text', 'Updated title')
r.callback(r.options)

How to update data of a chart

With a similar strategy as #how-to-modify-a-chart, we can update its data. This part depends on Papa Parse for handling of CSV, and as a result you are able to work on a column ordered CSV represented as a nested list.

const patchChartData = async (uuid) => {
    let chart = await getChart(uuid)
    chart.data = JSON.parse(chart.data)
    chart.details = JSON.parse(chart.details)

    chart.data.settings.dataProvider = chart.details

    let csv = await Papa.parse(chart.details.csv)

    const callback = async (data) => {
        chart.details.csv = Papa.unparse(data)
        return await post(`/${teamid}/data/${chart.dataId}`, JSON.stringify({
            data: JSON.stringify(chart.details),
        }))
    }

    return {
        options: csv.data,
        callback: callback
    }
}

We can call this much like last time:

let r = await patchChartData(uuid)
r.options[0][0] = 'Hello'
r.callback(r.options)