Retrieving data from a dashboard via API

Required system role: Integrator

DataTile dashboards can be used as a data source for Business Intelligence systems and other applications. DataTile will encapsulate all the complexity of the research domain and provide you with target KPIs via the JSon-based API.

While user-facing dashboards can be used for data delivery, in complex cases, we recommend creating separate dashboards that solely present the essential KPIs intended for integration.

Exposing dashboards via the API

The owner of a dashboard should explicitly grant access to it via API. Access to different dashboards should be enabled independently.

Open the dashboard you are going to expose;
Click the {api} icon in the toolbar to open the API popup window;
Switch the toggle button to enable API for the dashboard;
Copy the API URL to the current page of the dashboard
Copy the access token (and keep it secret) to authorize API calls

API token authorizes access to a particular dashboard. The system will forbid access to a dashboard with the token from another dashboard.

API Endpoints

It’s a JSON-based API. The root resource is a page (or tab) of a particular dashboard.

Here's an example:

This is a public version of a dummy dashboard exposed via API;
Its corresponding API endpoint;
The access token is: 89cd1a3b42ae440f9ce5c3ccaf1d7774

GET https://{SERVER}/api/v2/dashboards/{DASHBOARD_HASH}/api/{TAB_HASH}

returns the list of identified data elements (charts or tables) on the tab of the dashboard.

curl -H "token: 89cd1a3b42ae440f9ce5c3ccaf1d7774" https://cloud.datatile.eu/api/v2/dashboards/d4d2f7dd-0205-4b05-b4bf-1c3c8f11247f/api/6de5016ec9d04c49a54f162915add315

The request above returns the list of data elements on the dashboard as follows:

[
  {
     "id": 47170,
     "name": "tom-trend"
  },
  {
     "id": 47171,
     "name": "nps-scale" 
  }
]

To retrieve data from a widget widget individually, make the following call:

GET https://{SERVER}/api/v2/dashboards/{DASHBOARD_HASH}/api/{TAB_HASH}/{WIDGET_ID}

It returns the data structure behind the widget, including significance indicators:

[    
  "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"  
]

Example of request for the tom-trend (id=47170) widget:

curl -H "token: 89cd1a3b42ae440f9ce5c3ccaf1d7774" https://cloud.datatile.eu/api/v2/dashboards/d4d2f7dd-0205-4b05-b4bf-1c3c8f11247f/api/6de5016ec9d04c49a54f162915add315/47170

Example of API response:

[
   "25-35",
   "be_322575_1405798_78115",
   "Brand-3",
   "b276a59a-c25c-b971-b0e4-1d81cbf6d6e6",
   null,
   "16,Aug",
   "2973ee19-87d0-2efb-ef7d-f70e52a4a282$vpt",
   null, 
   "Vert%", 
   "vpt", 
   31.11685837,
   null,
   null
 ]

While a widget ID is unique and generated automatically by the DataTile server, you can configure the widget name to simplify navigation.

Both Widget name and ID can be acquired in the “Elements” section on the left panel of the dashboard settings.

The API doesn't support direct interaction with dashboard controls. If controls are present, the API delivers data based on their default states.