Push API Documentation

Getting Started

Dasheroo provides a flexible API that you may use to create visualizations for custom data in your business dashboards. Your application needs to simply send JSON-formatted data to a URL we provide and Dasheroo will handle the rest!

To get started, you need to add a Push API insight on the dashboard of your choice. You will be prompted to select the desired visualization. Currently, the choices are Line Chart, Area Chart, Pie Chart, Funnel, and Bar Graph. Once the insight is installed, click the “gear” icon and choose “Settings” from the insight menu (when adding one insight at a time, we open the Settings panel for you automatically).

Copy the custom URL created for the insight from the Settings panel, then click the “Connect” button. Your insight is now ready to receive your first packet of data!

Formatting Your Data

The data payload format for a Dasheroo Push API v2 insight uses standard JSON syntax, and it supports several keywords in the accepted key/value pairs. You may send as many distinct metrics in a single payload as you’d like recorded on your visualization. Be careful, though: too many metrics in a single chart can affect readability and reduce the impact or utility of your graphs!

The general format for a data payload looks something like this:

{
  "data":{
    "metric_1":{
      "type":"integer",
      "strategy": "interval",
      "label": "Metric 1",
      "value": 3
    }
  },
  "date":"2016-07-14"
}

At the top level, there are two primary keys: “data” and “date”. The “data” key contains all of the information about your metrics. In the example above, we’re sending only a single metric; however, you may send multiple metrics in the same format. The “date” key simply gives the date corresponding to the values that you are sending, in “YYYY-MM-DD” format. This key is optional and its value will default to the current date (in PST) unless otherwise specified. This can be useful for providing historical data to a fresh Push API insight when you initially connect it.

The “data” key is where your metrics reside. For visualizations that do not support ordered information, like Line, Area, and Pie charts, this data can be formatted in the same way. For ordered information, like Funnel and Bar graphs, the format changes slightly and will be covered in more detail below.

Unordered Metrics Payload

Your metrics can be formatted like this (multiple metrics need only to be listed in a comma-separated list of these):

"unique_metric_name": {
  "value": "metric_value",
  "type": "data_type",
  "strategy": "continuous_or_interval",
  "label": "Metric Display Name"
  }

More information about the keys above:

Value: this is the actual value of your statistic for the given date. This is a required key.

Type: this describes the type of data in the Value key above. This key is optional and the default value is “integer.” Supported data formats and values for this key are:

  • “integer” - whole numbers, only.
  • “float” - numbers which might contain a decimal portion
  • “currency” - numbers representing money. These values will be displayed with two decimal points and the symbol appropriate for your organization’s currency settings.
  • “percentage” - numbers representing percents. These values will be displayed with a percent sign (“%”) appended. Note that a value of “1.00” is considered to be “100%” and a value of “0.01” is considered to be “1%”. Percentage values can only be tracked using the continuous strategy (below).

Strategy: this describes the way data values over periods of time relate to one another. This key is optional and the default value is “continuous.” The two supported strategies are:

  • “continuous” - a rolling total which does not reset each day. An example would be the total size of a mailing list.
  • “interval” - a measure of change which resets to zero each day. An example would be the number of new subscribers today to a mailing list.

Label: this is the name you want to be displayed in the graph for this statistic. This key is optional and may contain a string value of your choice. Only one label value is stored for each metric, so updates to this value will affect historical as well as current and future displays.

As mentioned, multiple statistics can be sent for a given chart. In some cases, like Pie Charts, it only makes sense to send multiple metrics. To do so, simply construct multiple metrics payloads as described above. Using our example above, a multiple metric payload might look like this:

{
  "data":{
    "metric_1":{
      "type":"integer",
      "strategy": "interval",
      "label": "Metric 1",
      "value": 3
    },
    "metric_2":{
      "type":"float",
      "strategy": "interval",
      "label": "Metric 2",
      "value": 1.27
    }
  },
  "date":"2016-07-14"
}
Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request