Like the spies in Return of the Jedi, Bothan brings you information.

It’s a simple platform for storing and publishing metrics, both as JSON, and as simple, embeddable visualisations, which you can embded standalone in webpages, or use in dashboards. Take a look at the demo, or read the docs

Getting started

Getting started with Bothan is really simple. Simply click the button below to deploy your own free Bothan instance to Heroku (requires a free Heroku account, but you’ll be walked through the process if you don’t).


Your instance will come with a free mLab sandbox database, enough to store around 500,000 metrics. This can be upgraded any time via Heroku.


Adding data

All POST requests require a username and password (sent via basic auth)

POST https://username:[email protected]/metrics/{metric-name}

using a JSON content type, and with the following JSON in the body:

  "time": "{iso8601-date-time}",
  "value": ...

cURL example:

curl -X POST -H "Content-Type: application/json" -d '{
  "time": "2016-04-12T10:00:00",
  "value": 500
}' "https://username:[email protected]/metrics/simple-value"

value can be in any one of the following formats:

Simple value

The simplest format that a value can take is a single number. For example:

  "time": "{iso8601-date-time}",
  "value": 123

Value with a target

A value can also be a JSON object with an actual, annual_target and an optional ytd_target. For example:

  "time": "{iso8601-date-time}",
  "value": {
    "actual": 1091000,
    "annual_target": 2862000,
    "ytd_target": 1368000


  "time": "{iso8601-date-time}",
  "value": {
    "actual": 1091000,
    "annual_target": 2862000

Multiple values

If you want to track multiple values for one metric (for example, diversity data), we can do that too:

  "time": "{iso8601-date-time}",
  "value": {
    "total": {
      "value1": 123,
      "value2": 23213,
      "value4": 1235

### Adding metrics

If a {metric-name} is sent by a POST and does not already exist in the Bothan instance then a new metric will be created.

Deleting metrics

There is currently no way to delete a metric within an instance of Bothan.

Fetching data


Fetches list of available metrics


Fetches latest value for specified metric


Fetch the most recent value of the metric at the specified time. time is an ISO8601 date/time.


Fetch all values of the metric between the specified times. from and to can be either:


While this is primarily a JSON API, some of our endpoints will also serve HTML. Primarily:


(or GET{metric_name} which will redirect to a default time-range of the last 30 days)

query-string options

The rendering can be manipulated by the following query-string options:


One of:

Default: rich


One of:

Default: By default, Bothan will attempt to work out the best visualisation for your metric


Background colour for the chart or number, in hex. Note that you should not pass the leading #. Also note the English spelling

Default: ddd


Text colour (and line colour for the chart), in hex. Note that you should not pass the leading #. Also note the English spelling

Default: 222


meta-refresh interval for the page

Default: none


Setting metadata

You can also set a limited amount of metadata via the API and front-end:


Currently accepted API attributes are:

Sample request

  "type": "chart",
  "name": {
    "en": "My cool chart",
    "fr": "Mon tableau fraîche"
  "description": {
    "en": "A chart showing some great data",
    "fr": "Un tableau montrant un grand données"

A description can be set for the metric by logging into the Bothan instance on Heroku, selecting the metric and taking the option to ‘Edit Metadata’.


You can see a demo version with some pre-prepared metrics at

We’ve also put some of the demo metrics in a Jekyll-powered dashboard. You can check out the source on Github here.

To add your own metrics, follow the steps in the documentation, using the username username and the password password. The database is reset every day at 7am UTC.