Holistics Docs - End-to-End Business Intelligence Platform

Holistics Documentation

Welcome to the Holistics Documentation page. You'll find comprehensive guides and documentation to help you start working with Holistics as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started
Suggest Edits

Holistics API

 

Holistics API

We allow you to programmatically work with Holistics API. For example:

  • You can programmatically retrieve CSV, XLSX and JSON data from any Holistics report.
  • You can use our API to trigger execution of an email schedule, transform or data import.
  • etc...

This is useful especially if you need to pass live data to your other applications. For example, you may want to feed a live CSV endpoint of your user segmentation list into your email marketing application so that you can always get fresh data upon retrieving them.

API Key

To retrieve the data without the need to manually log in, you can generate a unique API key from each user's account.

Please visit your user settings and generate a user token.

New API Key

Then you can set the API key in request header and call our API. An example is our report data export API link.

API Request Authorization

When calling our API endpoints, we will authorize with your API key. Please set the custom X-Holistics-Key header to your API key.

Example:

curl -X POST \ 
  -H "Accept:application/json" \
  -H "Content-Type:application/json" \
  -H "X-Holistics-Key:api_key" \
  https://secure.holistics.io/data_imports/1/execute.json
Suggest Edits

Data Pipeline API

 

Data Pipeline API

This will be useful for setting up ETL workflow and controlling data pipeline on your side.

API Key

Please see guide to setup your API key.

Data Import

Execute Job

To execute a data import job, you will need to use the following HTTP endpoint:

POST /data_imports/<import_id>/execute.json

If successful, this endpoint will return the job ID of the job created.
To get the result, you will need to poll for the job data with:

GET /data_imports/job_result/<job_id>.json

Data Transform

Execute Job

The same to Data Import, you can execute a data transform job with:

POST /data_transforms/<transform_id>/execute.json

Job Logs

You can view information about the running job using this endpoint:

GET jobs/<job_id>/logs.json

Check Last Run of Imports/Transforms

Sometimes you want to run a custom processing job daily at a particular time, but only if the ETL jobs ran successfully.
And you need a way to check the status of the ETL jobs.

In that case, you can use the jobs/get_last_jobs.json endpoint.

Parameters:

  • source_type: DataImport or DataTransform
  • ids: array of your transform/import IDs

Sample Request:

GET /jobs/last_run_jobs.json?source_type=DataTransform&ids[]=123&ids=[]456

Sample Responses:

{
  "123": {
    "id":11106256,
    "status":"running",
    "start_time":"2017-12-12T04:30:31Z",
    "end_time":null,
    "created_at":"2017-12-12T04:30:31Z"
  },
  "456": {
      "id":11106257,
      "status":"success",
      "start_time":"2017-12-12T04:30:31Z",
      "end_time":"2017-12-12T05:30:31Z",
      "created_at":"2017-12-12T04:30:31Z"
  }
}
Suggest Edits

Getting Report Data API

 

Reports API

This is useful especially if you need to pass live data to your other applications. For example, you may want to feed a live CSV endpoint of your user segmentation list into your email marketing application so that you can always get fresh data upon retrieving them.

API Key

Please see guide to setup your API key.

Submit Report Query

To submit a report query job, you will need to use the following HTTP endpoint:

GET /queries/<report_id>/submit_query.json?<filter_param1>=<filter_value1>...

If successful, this endpoint will return the job ID of the job created. To get the result, you will need to poll for the job status with

GET /queries/get_query_results.json?&job_id=<job_id>

Do note that the results are paginated, look into the paginated section of the response JSON for more information. To fetch the next page of data, append &_page=<page_number> to the URL.

Params:

  • _page_size: (optional) set the page size of the response
  • _page: (optional) set the page number of data to fetch

Submit Report Export Job

In order to download the CSV or Excel for a report's result set, you will need to use the following:

GET /queries/<report_id>/submit_export.<format>?<filter_param1>=<filter_value1>...
  • Supported format: csv/json/xlsx

Or if your query string is too long (> 500 letters), you can consider using a POST request:

POST /queries/<report_id>/submit_export.<format>

In the request body, specify the filter values in JSON format:

{
  "customer_ids": [1, 2, 3],
  "status": "active"
}
  • Supported format: csv/json

If successful, the endpoint will return the job ID for the export job created. To get the result, you will need to poll for the job status with either of these endpoints:

GET /queries/get_export_results.json?job_id=<job_id>

or this endpoint:

GET /jobs/<job_id>/get_results.json

Once the job status is 'success', you can download the result file via exports/download endpoint

GET /exports/download?job_id=<job_id>

Small dataset (< 10K rows)


This API is deprecated. Please use the asynchronous submit_export API instead.

For a small dataset (less than 10 thoudsands rows), you can use just this endpoint to download the data:

GET https://secure.holistics.io/queries/<report_id>.<format>?<filter_param1>=<filter_value1>...

How often does these API data refresh?

This is based on your report cache duration that you set in the report.

Suggest Edits

Permissions API

 

Permissions API

Share/Unshare Reports with Users

This allow you to share/unshare reports/dashboard with users

POST /permissions/share.json
POST /permissions/unshare.json
{
  "actions": [
    {
      "actor_class": "User",
      "actor_id": 123,
      "action": "read",
      "subject_class": "QueryReport",
      "subject_id": 456
    }
  ]
}
  • Available actor_class: User, Group
  • Available subject_class: QueryReport, Dashboard
  • Available action: read

The above example will simulate an action of current user (via API authentication), sharing report 456
with another user (id: 123), allowing user 123 to be able to read the report.

Suggest Edits

Package for Python

 

Our package (Holistics Package for Python) allow Python's user export report's data by inputting:

  • Your API-key
  • Report's ID
  • Dictionary of filters applied to that report

Notes:

Supported output format: DataFrame object, .CSV
Python version: >= 3, < 4


Installation

Package can be installed with pip:

pip install holistics

Alternatively, you can grab the latest source code from GitHub:

git clone git://github.com/holistics/holistics-python.git
cd holistics-python
python setup.py install


How to export data

Beginning by import holistics package

from holistics import HolisticsAPI


Next, creating an object of HolisticsAPI class with your API-key and Holistics server's url

obj = HolisticsAPI(api_key = 'aerg454hoiaKJGlgku', url = 'demo.holistics.io')

Args:


Finally, call export_data function with specific syntax:
    export_data (report_id, path, filters, page_size, page)

my_dataframe = obj.export_data(report_id='123456', path='C:/output.csv', 
                              filters={'date': '2017-04-28', 'vat': 1.1}, 
                              page_size = 12, page = 5)

Args:

  • report_id (str): ID of report. Get from URL.
  • path (str) (optional): If you want to store export data to local path, set path variable.
    • Default value: None
    • Ex: 'D:/Data/output.csv'
  • filters (dict) (optional): dictionary of filters that would be applied to report.
    • Default value: None
    • Ex: {'tenant': 'holistics', 'date': '2017-04-28'}
  • page_size (int) (optional): Set the page size of the response.
    • Default value: 10000000
  • page (int) (optional): Set the page number of data to fetch.
    • Default value: 10000000

Return:

A DataFrame object. If path is not None, save object as .csv file at that path.

Raises:

  • HTTPError: If the program can't connect to target site and get data.
    • You should check your API-key, url of Holistics and internet connection.
  • RuntimeError: If return status is Failure.
    • It could be caused by wrong SQL of your QueryReport.
  • ParserError: If program can't parse downloaded data as DataFrame object.
    • It could be caused when downloaded data is None.
Suggest Edits

Job Info

Get the info and status of a job

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.holistics.io/jobs/job_id.json
curl --request GET \
  --url https://api.holistics.io/jobs/job_id.json
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.holistics.io/jobs/job_id.json' };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.holistics.io/jobs/job_id.json")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.holistics.io/jobs/job_id.json");

xhr.send(data);
import requests

url = "https://api.holistics.io/jobs/job_id.json"

response = requests.request("GET", url)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "id": 1138,
    "status": "success",
    "created_at": "2018-08-24T08:19:19.596Z",
    "source_id": 3,
    "source_type": "DataImport",
    "user_id": 3,
    "start_time": "2018-08-24T08:19:20.670Z",
    "end_time": "2018-08-24T08:19:20.924Z",
    "tenant_id": 2,
    "duration": 0.253676,
    "cancellable": true,
    "source_method": "execute"
}

Path Params

job_id
int32
required
 
Suggest Edits

Last Run Jobs

Get the last jobs of the specified sources.

 

Header Auth

 Authentication is required for this endpoint.
gethttps://api.holistics.io/jobs/last_run_jobs.json
curl --request GET \
  --url 'https://api.holistics.io/jobs/last_run_jobs.json?source_type=source_type&ids=ids'
var request = require("request");

var options = { method: 'GET',
  url: 'https://api.holistics.io/jobs/last_run_jobs.json',
  qs: 
   { source_type: 'source_type',
     ids: 'ids' } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});
require 'uri'
require 'net/http'

url = URI("https://api.holistics.io/jobs/last_run_jobs.json?source_type=source_type&ids=ids")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body
var data = JSON.stringify(false);

var xhr = new XMLHttpRequest();
xhr.withCredentials = true;

xhr.addEventListener("readystatechange", function () {
  if (this.readyState === this.DONE) {
    console.log(this.responseText);
  }
});

xhr.open("GET", "https://api.holistics.io/jobs/last_run_jobs.json?source_type=source_type&ids=ids");

xhr.send(data);
import requests

url = "https://api.holistics.io/jobs/last_run_jobs.json"

querystring = {"source_type":"source_type","ids":"ids"}

response = requests.request("GET", url, params=querystring)

print(response.text)
A binary file was returned

You couldn't be authenticated

{
    "3": {
        "id": 1138,
        "status": "success",
        "start_time": "2018-08-24T08:19:20Z",
        "end_time": "2018-08-24T08:19:20Z",
        "created_at": "2018-08-24T08:19:19Z"
    }
}

Query Params

source_type
string
required

Possible values: 'DataImport', 'DataTransform', 'EmailSchedule', 'ScheduleCache'

ids
array of strings
required

IDs of the jobs' sources. These sources must have the same type specified in param source_type

 

Example request to get last jobs of DataImports 1 and 3

/jobs/last_run_jobs.json?source_type=DataImport&ids[]=1&ids[]=3
{
    "1": {
        "id": 1147,
        "status": "failure",
        "start_time": "2018-08-24T09:11:23Z",
        "end_time": "2018-08-24T09:11:23Z",
        "created_at": "2018-08-24T09:11:22Z"
    },
    "3": {
        "id": 1138,
        "status": "success",
        "start_time": "2018-08-24T08:19:20Z",
        "end_time": "2018-08-24T08:19:20Z",
        "created_at": "2018-08-24T08:19:19Z"
    }
}