API

We’ve built a REST API that allows you to send us formatted data as a JSON payload. There are much faster ways to connect a range of common cloud services (e.g. Google Analytics, Mixpanel, Salesforce) to Databox. However, if your favorite service is not yet on our list, or you have your own private data that you’d like to see in Databox, you’ve come to the right place.

First, get your token

You’ll need a token to send us data. This is your authorization for Databox API. Sharing is caring. But not with this. Keep it secret!

Sign up for a Databox account. You’ll use the same account for pushing and accessing your data on your phone - no extra developer account needed!

Next, grab your pre-assigned (‘Token’) token either from the Designer onboarding flow (choose ‘Push own data’), or create a new one on ‘Available data sources’ page as shown below:

Adding new custom data source

You can add as many custom sources as you’d like. You can see all your sources here, along with tokens for the custom ones:

Getting custom data source token

Read more about data sources and tokens.
Don’t have your Databox account yet? Sign up here!

Then, send your data

You can try sending us data quickly right from your terminal. However, you’re probably going to want to automate it. Our SDKs can help you do that fast in your favorite language.

Note: Don’t forget to change the example token below to your own.

  • curl
  • php
  • js
  • ruby
  • java
  • go
  • python
curl https://push.databox.com \
-u 2cdt4yoytbvockc51cowgs4gsss84ow4s: \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/vnd.databox.v2+json' \
-d '{
  "data":[
    {
      "$sales": 123000
    }
  ]
}'
use Databox\Client;

$c = new Client('2cdt4yoytbvockc51cowgs4gsss84ow4s');

$ok = $c->push('sales', 123000);
var Databox = require('databox');

var client = new Databox({
    push_token: '2cdt4yoytbvockc51cowgs4gsss84ow4s'
});

client.push({
    key: 'sales',
    value: 123000
}, function(response){
    console.log(response);
});
Databox.configure do |c|
  c.push_token = '2cdt4yoytbvockc51cowgs4gsss84ow4s'
end

client = Databox::Client.new

client.push(key: 'sales', value: 123000)
String TOKEN = "2cdt4yoytbvockc51cowgs4gsss84ow4s";
Databox databox = new Databox(TOKEN);
try {
  databox.push("sales", 123000d);
} catch (Exception e) {
  System.err.println(e.getLocalizedMessage());
}
package main

import (
    databox "github.com/databox/databox-go"
    "fmt"
)

func main() {
    client := databox.NewClient("2cdt4yoytbvockc51cowgs4gsss84ow4s")

    if status, _ := client.Push(&databox.KPI{
        Key:    "sales",
        Value:  123000
    }); status.Status == "ok" {
        fmt.Println("Inserted.")
    }
}
from databox import Client

client = Client('2cdt4yoytbvockc51cowgs4gsss84ow4s')
client.push('sales', 123000)

Note: the dollar sign ($) before metric name is mandatory, but if you’re using an SDK, it’ll be prepended automatically. This character is used to differentiate a metric from its attributes. Read more about metric attributes here.

Important: A metric must be purely numeric. If you have currency values or percentages, send only the number, but set up a proper format for your metric in the Databox Designer. Read how to do that here.

You can also send multiple metrics at once like so:


curl https://push.databox.com \
-u 2cdt4yoytbvockc51cowgs4gsss84ow4s: \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/vnd.databox.v2+json' \
-d '{
  "data":[
    {
      "$sales": 123000,
      "$expenses": 87500
    }
  ]
}'

Terminal panel in Databox Designer

If you’re less technical and wary of command lines or SDKs, you can also manually send your data through the Terminal panel in the Databox Designer. Just select the appropriate data source at the bottom, change the data and press the “Push” button!

Databox Designer Terminal panel

This is a simple and quick way to test-drive your syntax and visualization at the same time.

Data attributes

You can add arbitrary attributes to your data items like this:

  • curl
  • php
  • js
  • ruby
  • java
  • go
  • python
curl https://push.databox.com \
-u 2cdt4yoytbvockc51cowgs4gsss84ow4s: \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/vnd.databox.v2+json' \
-d '{
  "data":[
    {
      "$sales": 83000,
      "channel": "online"
    },
    {
      "$sales": 4000,
      "channel": "retail"
    },
    {
      "$sales": 123000,
      "$expenses": 87500,
      "channel": "in-person"
    }
  ]
}'
use Databox\Client;

$c = new Client('2cdt4yoytbvockc51cowgs4gsss84ow4s');

$c->insertAll([
    ['sales', 83000, null, [
      'channel' => 'online'
    ]],
    ['sales', 4000, null, [
      'channel' => 'retail'
    ]],
]);
var Databox = require('databox');

var client = new Databox({
    push_token: '2cdt4yoytbvockc51cowgs4gsss84ow4s'
});

client.insertAll([
  {
    key: 'sales',
    value: 83000,
    attributes: {
      'channel': 'online'
    }
  },
  {
    key: 'sales',
    value: 4000,
    attributes: {
      'channel': 'retail'
    }
  }
]);
Databox.configure do |c|
  c.push_token = '2cdt4yoytbvockc51cowgs4gsss84ow4s'
end

client = Databox::Client.new

client.insert_all [
    {key: 'sales', value: 83000, attributes: {
      channel: 'online'
    }},
    {key: 'sales', value: 4000, attributes: {
      channel: 'retail'
    }}
]
String TOKEN = "2cdt4yoytbvockc51cowgs4gsss84ow4s";
Databox databox = new Databox(TOKEN);
try {
  List<Databox.KPI> kpis = new ArrayList<Databox.KPI>();
  SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss", Locale.getDefault());
  kpis.add(new Databox.KPI().setKey("sales").setValue(83000).addAttribute("channel", "online"));
  kpis.add(new Databox.KPI().setKey("sales").setValue(4000).addAttribute("channel", "retail"));
  databox.push(kpis);
} catch (Exception e) {
  System.err.println(e.getLocalizedMessage());
}
package main

import (
    databox "github.com/databox/databox-go"
    "fmt"
)

func main() {
    client := databox.NewClient("2cdt4yoytbvockc51cowgs4gsss84ow4s")

    var attributes = make(map[string]interface{})
    attributes["channel"] = "online"

    if status, _ := client.Push(&databox.KPI{
        Key: "sales",
        Value: 83000,
        Attributes: attributes,
    }); status.Status == "ok" {
        fmt.Println("Ok!")
    }
}
from databox import Client

client = Client('2cdt4yoytbvockc51cowgs4gsss84ow4s')
client.insert_all([
    {'key': 'sales', 'value': 83000, attributes={
      'channel': 'online',
    }},
    {'key': 'sales', 'value': 4000, attributes={
      'channel': 'retail',
    }},
])

Note: If you send an attribute along with multiple metrics, the attribute will be added to each metric.

Now, you can filter and visualize your data by a these attributes: show only retail sales, or compare sales across different channels. You can add any number of custom attributes to the same metric. In fact, some visualizations in Databox can be used only with metrics that have associated attributes (e.g. a single-source table shown below).

Single-source table datablock

Read more about single- vs. multiple- source datablocks here.

Units

Similar to data attribute, you can also attach a unit value to your data. The difference between the two is that while attribute provides extra information (like, which store that $sales: 230 came from), unit describes the value itself (what is that 230). Most often unit is used to separate different currencies, but the possibilities are endless, as you can use any string as a unit.

  • curl
  • php
  • js
  • ruby
  • java
  • go
  • python
curl https://push.databox.com \
-u 2cdt4yoytbvockc51cowgs4gsss84ow4s: \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/vnd.databox.v2+json' \
-d '{
  "data":[
    {
      "$sales": 50000,
      "unit": "USD"
    },
    {
      "$sales": 33000,
      "unit": "EUR"
    }
  ]
}'
Not supported yet
Not supported yet
Not supported yet
Not supported yet
Not supported yet
Not supported yet

In Databox, your units will appear in number or table listed one after another. Aggregations and other functions will be applied to each unit separately, so you never mix your dollars with yens.

Still not sure if you should be using a unit or an attribute? Simply put, if your data still makes sense when sumed up, use attributes instead.

Date and time

Specifying dates and times is optional, but doing so makes it easy to store historical data in Databox for more sophisticated graphs and alerting.

  • curl
  • php
  • js
  • ruby
  • java
  • go
  • python
curl https://push.databox.com \
-u 2cdt4yoytbvockc51cowgs4gsss84ow4s: \
-X POST \
-H 'Content-Type: application/json' \
-H 'Accept: application/vnd.databox.v2+json' \
-d '{
  "data":[
    {
      "$sales": 83000,
      "date": "2016-01-19"
    },
    {
      "$sales": 4000,
      "date": "2016-01-20 16:07:37-06:00"
    }
  ]
}'
use Databox\Client;

$c = new Client('2cdt4yoytbvockc51cowgs4gsss84ow4s');

$c->insertAll([
    ['sales', 83000, '2016-01-19'],
    ['sales', 4000, '2016-01-20 16:07:37-06:00'],
]);
var Databox = require('databox');

var client = new Databox({
    push_token: '2cdt4yoytbvockc51cowgs4gsss84ow4s'
});

client.insertAll([
  {
    key: 'sales',
    value: 83000,
    date: '2016-01-19'
  },
  {
    key: 'sales',
    value: 4000,
    date: '2016-01-20 16:07:37-06:00'
  }
]);
Databox.configure do |c|
  c.push_token = '2cdt4yoytbvockc51cowgs4gsss84ow4s'
end

client = Databox::Client.new

client.insert_all [
    {key: 'sales', value: 83000, date: '2016-01-19'},
    {key: 'sales', value: 4000, date: '2016-01-20 16:07:37-06:00'}
]
String TOKEN = "2cdt4yoytbvockc51cowgs4gsss84ow4s";
Databox databox = new Databox(TOKEN);
try {
    List<Databox.KPI> kpis = new ArrayList<Databox.KPI>();
    SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss", Locale.getDefault());
    kpis.add(new Databox.KPI().setKey("sales").setValue(83000).setDate(sdf.parse("2016-01-19")));
    kpis.add(new Databox.KPI().setKey("sales").setValue(4000).setDate(sdf.parse("2016-01-20 16:07:37-06:00")));
    databox.push(kpis);
} catch (Exception e) {
    System.err.println(e.getLocalizedMessage());
}
package main

import (
    databox "github.com/databox/databox-go"
    "fmt"
)

func main() {
    client := databox.NewClient("2cdt4yoytbvockc51cowgs4gsss84ow4s")

    if status, _ := client.Push(&databox.KPI{
        Key:    "sales",
        Value:  83000,
        Date:   "2016-01-19",
    }); status.Status == "ok" {
        fmt.Println("Inserted.")
    }
}
from databox import Client

client = Client('2cdt4yoytbvockc51cowgs4gsss84ow4s')
client.insert_all([
    {'key': 'sales', 'value': 83000, 'date': '2016-01-19'},
    {'key': 'sales', 'value': 4000, 'date': '2016-01-20 16:07:37-06:00'},
])

Date format like this 2016-01-19 will translate into 2016-01-19 00:00:00 UTC. If you omit the date parameter, midnight (UTC) on the current date will be used by default. To avoid discrepancies in your data, you should doublecheck that all the data has either timezone explicitly specified, or is in UTC.

If you send the same metric with the same exact date twice, the new record overwrites the old one.

Behind the scenes, Javascript Date.parse() is used, so you can specify date, time and even time zone if necessary, as long as you follow the ISO 8601 standard.

Verification and testing

To verify what’s going on with your pushed data, you can query the following endpoint (use your token!).

  • curl
  • php
  • js
  • ruby
  • java
  • go
  • python
curl https://push.databox.com/lastpushes \
  -u 2cdt4yoytbvockc51cowgs4gsss84ow4s: \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/vnd.databox.v2+json'
use Databox\Client;

$c = new Client('2cdt4yoytbvockc51cowgs4gsss84ow4s');

$lastPushes = $c->lastPush(5);
var Databox = require('databox');

var client = new Databox({
    push_token: '2cdt4yoytbvockc51cowgs4gsss84ow4s'
});

client.lastPushes(10, function (pushes) {
    console.log(pushes);
});
Databox.configure do |c|
  c.push_token = '2cdt4yoytbvockc51cowgs4gsss84ow4s'
end

client = Databox::Client.new

client.last_push(5)
String TOKEN = "2cdt4yoytbvockc51cowgs4gsss84ow4s";
Databox databox = new Databox(TOKEN);
try {
    StringBuffer lastPushes = databox.lastPushes(5);
    System.out.println(lastPushes);
} catch (Exception e) {
    logger.error(e.getLocalizedMessage(), e);
}
package main

import (
    databox "github.com/databox/databox-go"
    "fmt"
)

func main() {
    client := databox.NewClient("2cdt4yoytbvockc51cowgs4gsss84ow4s")

    if data, _ := client.LastPush() ; data != nil {
        fmt.Println(string(data))
    }
}
from databox import Client

client = Client('2cdt4yoytbvockc51cowgs4gsss84ow4s')

print client.last_push(5)

This will return last sent data package (or packages, if you add the count in the URL like so https://push.databox.com/lastpushes/5) in the following format:

[
  {
    "push":"{\"data\":[{\"$sales\":123000}]}",
    "err":"[]",
    "no_err":0,
    "datetime":"2016-01-21T08:53:03.914Z",
    "keys":"[\"1375|sales\"]"
  }
]

Responses and errors

If all goes well with your data push, you’ll receive a response like this:

HTTP/1.1 200 OK
Content-Type: application/json

{"status":"ok"}

But, c’mon, how often does life go as planned?
Possible error responses are listed below.

{"status":"Error: No authorization sent”}
{"status":"Error: Unauthorized - check your token”}
{"status":"Error: Too many requests 10/sec is allowed”}
{"status":"Error: Content type should be application/json”}
{"status":"Error: JSON format error or JSON empty”}
{"status":"Error: JSON should be wrapped up in \'data\' item”}
{"status":"Error: \'data\' element should contain array of items not single item only”}

If you get a warning like this:

{"status":"Warning: some items not inserted (ok: 0, false: 1)”}

you should make sure your data follow these rules:

  • the metric name has a $ prepended
  • the metric value is a number (float is allowed)
  • the date, if specified, conforms to the ISO 8601 standard and is compatible with JavaScript Date.parse()

Are you stuck? You're always welcome to contact us - we're here to help!