Working with Data via API

There are several ways for working with APIs in Holistics, you can refer to the full documentation here.

For getting data via API, you can use our HTTP API methods and Python package.

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>

Pushing CSV data back into Holistics via CLI#

For more details on setting up the Holistics gem for command line tools, you can refer to our Holistics CLI documentation.

Once you have setup the Holistics gem for your CLI tool, authenticate your API token in your CLI.

$ holistics login <token>
Authenticating token...
Authentication successful. Info:
- ID: 1
- Email: [email protected]

Type holistics help for a full list of CLI commands. For example, you can re-import CSV data that you have worked on into Holistics, using the following command:

holistics import csv -d, --dest-ds-id=DEST_DS_ID -f, --filepath=FILEPATH -t, --dest-table-name=DEST_TABLE_NAME  ## Import a local CSV file to destination server

More details on importing via CLI can be found using help:

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:

api_key (str): Your account's API-key.
- How to generate API-key
url (str) (optional): URL of your Holistics server
- Default value: 'https://secure.holistics.io'

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.
- Ex: https://secure.holistics.io/queries/12345-processing-report (12345)
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.

Finding your Source ID and Source Type#

The Source ID and Type could get easily by viewing on the URL: https://secure.holistics.io/sample-name. The type is mapped to Source Type by this table below:

Type	SourceType
queries	QueryReport
dashboards	Dashboard
metrics/sheet	MetricSheet

For example, we have an URL: https://secure.holistics.io/queries/11111-table-with-dropdown-filter. 11111 is the Source ID, and the type is QueryReport (mapped from queries)