Retrieving data from DataTile Dashboard Data API

This document uses a dummy dashboard Brand KPIs as an example.

This dashboard has a single tab (page) containing one control and two charts.

Dashboard	Brand KPIs
Public link	https://cloud.datatile.eu/view/e764fc96fba84013a3e1eb8683c23f04
HASH	`a07329df9a0c472db14ad6bbd8a503d3`
iFrame code	CODE `<iframe frameBorder="0" src="https://cloud.datatile.eu/dashboard/embedded/e764fc96fba84013a3e1eb8683c23f04" width="100%" height="100%"> </iframe>`
API Key (token)	`2414e5bd-0fcb-4a4d-815a-ac61b6915243`

API

We will be using the following parameters/placeholders in the scripts and examples:

BASE_URL is the address of your DataTile instance. E.g. https://cloud.datatile.eu
ACCESS_TOKEN - is the secret token, an alphanumeric string retrieved from a dashboard page in DataTile. An access token is generated for each dashboard to enable read access to it via the API.
HASH - identifier of a dashboard.

Class diagram

Authentication

Token-based authentication. Token to be provided as an HTTP header of every API call.

CURL example:

CODE

curl https://cloud.datatile.eu/api/v2/dashboards/${HASH}
   -H "token: ACCESS_TOKEN"
   -H "Content-Type: application/json"

Only the owner of the dashboard can expose it via API and generate an access token. Other users cannot change this configuration disregarding their permission level.

To get an access token, follow the steps below:

Open the dashboard (being its owner).
Click the {api} icon at the page header.
Enable API key access in the pop-up window.
The secret token is not rendered on the screen. Click the “COPY API KEY” button to copy it to your clipboard.

You can regenerate the API key to drop existing connections. This operation is irrevocable. The system will issue a new API token. This will invalidate the previous token hence all integrations will lose access to the dashboard.

API Endpoints

Get dashboard tabs

GET ${BASE_URL}/api/v2/dashboards/${HASH}/api - retrieves the list of the dashboard tabs

Response:

CODE

[
    {
        "id": "342bbc0c1b534d5baa05c10d298c027c",
        "name": "Brand KPIs"
    }
]

Get tab widgets

GET /api/v2/dashboards/${DASHBOARD_HASH}/api/${TAB_HASH} - retrieves the list of the widgets (elements, tables, charts) available on the tab (page) of the dashboard.

Response:

CODE

[
    {
        "id": 5751,
        "name": "brand-awareness"
    },
    {
        "id": 5760,
        "name": "brand-consumption"
    }
]

Get widget

GET /api/v2/dashboards/${DASHBOARD_HASH}/api/${TAB_HASH}/${WIDGET_ID} - fetches data of the widget.

Response:

CODE

[
  ["split_name","split_id","row_name","row_id","row_alias","column_name","column_id","column_alias","metric_name""metric_id","value","s10e1_value","s10e2_value"],
  ["n","n","TOM","be_5756_441240_441241$vpt", null, "2017'Q1", "48d6f747-956f-6dc8-a607-e1bd9951f587", null, "Vert%", "vpt", 0.0, null, null],
  ["n","n","TOM","be_5756_441240_441241$vpt",null,"2017'Q2","07407109-b6d8-47db-d9e5-3b26877e6774",null,"Vert%","vpt",0.623529412,null,null],
  ["n","n","TOM","be_5756_441240_441241$vpt",null,"2017'Q3","bd3ca3a4-b1a4-114a-0e2f-8963ebb45c18",null,"Vert%","vpt",1.158823529,"high",null],
  ["n","n","TOM","be_5756_441240_441241$vpt",null,"2017'Q4","e9302d07-49aa-5290-37b5-cc9f3c510195",null,"Vert%","vpt",1.817647059,"high",null],
  ["n","n","TOM","be_5756_441240_441241$vpt",null,"2018'Q1","33b2eb1d-164a-5076-8b2a-5afc81dc5cdf",null,"Vert%","vpt",1.788235294,null,null],
  ["n","n","TOM","be_5756_441240_441241$vpt",null,"2018'Q2","ffcc0033-1d55-7953-6460-82e2d2c749a7",null,"Vert%","vpt",2.229411765,"high",null],
  ["n","n","TOM","be_5756_441240_441241$vpt",null,"2018'Q3","02764711-06aa-71a2-4838-044a92f6a8bf",null,"Vert%","vpt",2.7,"high",null],
  ["n","n","TOM","be_5756_441240_441241$vpt",null,"2018'Q4","6fcdfae6-3188-838e-5a8e-17c0b685ef94",null,"Vert%","vpt",4.017647059,"high",null],
  ["n","n","Unaided awareness","be_5756_441240_441242$vpt",null,"2017'Q1","48d6f747-956f-6dc8-a607-e1bd9951f587",null,"Vert%","vpt",0.0,null,null],
  ["n","n","Unaided awareness","be_5756_441240_441242$vpt",null,"2017'Q2","07407109-b6d8-47db-d9e5-3b26877e6774",null,"Vert%","vpt",2.223529412,null,null],
  ["n","n","Unaided awareness","be_5756_441240_441242$vpt",null,"2017'Q3","bd3ca3a4-b1a4-114a-0e2f-8963ebb45c18",null,"Vert%","vpt",4.723529412,"high",null],
  ["n","n","Unaided awareness","be_5756_441240_441242$vpt",null,"2017'Q4","e9302d07-49aa-5290-37b5-cc9f3c510195",null,"Vert%","vpt",5.976470588,"high",null],
  ["n","n","Unaided awareness","be_5756_441240_441242$vpt",null,"2018'Q1","33b2eb1d-164a-5076-8b2a-5afc81dc5cdf",null,"Vert%","vpt",6.811764706,"high",null],
  ["n","n","Unaided awareness","be_5756_441240_441242$vpt",null,"2018'Q2","ffcc0033-1d55-7953-6460-82e2d2c749a7",null,"Vert%","vpt",8.835294118,"high",null],
  ["n","n","Unaided awareness","be_5756_441240_441242$vpt",null,"2018'Q3","02764711-06aa-71a2-4838-044a92f6a8bf",null,"Vert%","vpt",11.005882353,"high",null],
  ["n","n","Unaided awareness","be_5756_441240_441242$vpt",null,"2018'Q4","6fcdfae6-3188-838e-5a8e-17c0b685ef94",null,"Vert%","vpt",13.870588235,"high",null],
  ["n","n","AD awareness","be_5756_441240_441306$vpt",null,"2017'Q1","48d6f747-956f-6dc8-a607-e1bd9951f587",null,"Vert%","vpt",0.0,null,null],
  ["n","n","AD awareness","be_5756_441240_441306$vpt",null,"2017'Q2","07407109-b6d8-47db-d9e5-3b26877e6774",null,"Vert%","vpt",3.064705882,null,null],
  ["n","n","AD awareness","be_5756_441240_441306$vpt",null,"2017'Q3","bd3ca3a4-b1a4-114a-0e2f-8963ebb45c18",null,"Vert%","vpt",9.658823529,"high",null],
  ["n","n","AD awareness","be_5756_441240_441306$vpt",null,"2017'Q4","e9302d07-49aa-5290-37b5-cc9f3c510195",null,"Vert%","vpt",14.082352941,"high",null],
  ["n","n","AD awareness","be_5756_441240_441306$vpt",null,"2018'Q1","33b2eb1d-164a-5076-8b2a-5afc81dc5cdf",null,"Vert%","vpt",12.905882353,"low",null],
  ["n","n","AD awareness","be_5756_441240_441306$vpt",null,"2018'Q2","ffcc0033-1d55-7953-6460-82e2d2c749a7",null,"Vert%","vpt",13.064705882,null,null],
  ["n","n","AD awareness","be_5756_441240_441306$vpt",null,"2018'Q3","02764711-06aa-71a2-4838-044a92f6a8bf",null,"Vert%","vpt",16.117647059,"high",null],
  ["n","n","AD awareness","be_5756_441240_441306$vpt",null,"2018'Q4","6fcdfae6-3188-838e-5a8e-17c0b685ef94",null,"Vert%","vpt",16.858823529,null,null],
  ["n","n","Promted awareness","be_5756_441240_441243$vpt",null,"2017'Q1","48d6f747-956f-6dc8-a607-e1bd9951f587",null,"Vert%","vpt",0.0,null,null],
  ["n","n","Promted awareness","be_5756_441240_441243$vpt",null,"2017'Q2","07407109-b6d8-47db-d9e5-3b26877e6774",null,"Vert%","vpt",5.188235294,null,null],
  ["n","n","Promted awareness","be_5756_441240_441243$vpt",null,"2017'Q3","bd3ca3a4-b1a4-114a-0e2f-8963ebb45c18",null,"Vert%","vpt",9.658823529,"high",null],
  ["n","n","Promted awareness","be_5756_441240_441243$vpt",null,"2017'Q4","e9302d07-49aa-5290-37b5-cc9f3c510195",null,"Vert%","vpt",15.052941176,"high",null],
  ["n","n","Promted awareness","be_5756_441240_441243$vpt",null,"2018'Q1","33b2eb1d-164a-5076-8b2a-5afc81dc5cdf",null,"Vert%","vpt",13.888235294,"low",null],
  ["n","n","Promted awareness","be_5756_441240_441243$vpt",null,"2018'Q2","ffcc0033-1d55-7953-6460-82e2d2c749a7",null,"Vert%","vpt",15.082352941,"high",null],
  ["n","n","Promted awareness","be_5756_441240_441243$vpt",null,"2018'Q3","02764711-06aa-71a2-4838-044a92f6a8bf",null,"Vert%","vpt",17.147058824,"high",null],
  ["n","n","Promted awareness","be_5756_441240_441243$vpt",null,"2018'Q4","6fcdfae6-3188-838e-5a8e-17c0b685ef94",null,"Vert%","vpt",19.929411765,"high",null]
]