API

API Endpoint

All API URLs listed in this documentation are relative to https://jolicharts.com/api/. For example, the /dashboard/duplicate API call is reachable at https://jolicharts.com/api/dashboard/duplicate.

RESTful

The Jolicharts API is a mostly RESTful API. Known caveats:

  • All API calls should be made with HTTP POST.
  • You can consider any non-200 HTTP response code an error - the returned data will contain more detailed information
  • All methods are accessed via: https://jolicharts.com/api/CLASS/SOME-METHOD?PARAMS

Passing Request Data

Request data is passed to the API by POSTing JSON objects to the API endpoints using the queryData parameter. The documentation for each API call will contain more details on the parameters accepted by the call. As an alternative, you can also use HTTP POST parameters, just like submitting an HTML FORM, but JSON objects are recommended.

Output Formats

We support two output formats. To use any of them, simply replace precise the format parameter in your request with one of:

  • json (default)
  • xml
The response data for each call will the be encoded in the specified format. If nothing is precised data will be output in JSON. Regardless of the output format desired, inputs are only accepted as HTTP POST parameters.

API Playground

Use the API Playground to try out your API calls without having to install anything. You just need a valid Dashboard API Key.

Questions? Problems?

Have you run into difficulties or a method just doesn't seem to work right? Check out our Support center and we'll be happy to assist you.

API Call Classes

dashboard

datasource

sheet

dashboard

  • createDatasource ( string dashboard , [ string datasourceName ] )
    Creates a new empty datasource in the dashboard using the provided datasource name. Returns the unique code of the created datasource.
  • delete ( string dashboard )
    Deletes the dashboard and all related elements.
  • duplicate ( string dashboard , [ bool duplicateData , bool duplicateUsers , string name ] )
    Duplicates the dashboard and all its related elements (sheets, dashboard elements,...). Optionally it is possible to duplicate the data of the dashboard and the user rights. If the dashboard data is not duplicated, datasources will be duplicated but will not contain any files and the charts will remain empty.
  • copyData ( string dashboard string targetDashboard )
    Copies all the datasources and data belonging to a specified dashboard (source dashboard) to another dashboard (target dashboard). All the data of the target dashboard will be replaced by the data of the source dashboard. The sheets and elements belonging to the target dashboard will not be modified.
  • get ( string dashboard )
    Gets information about the dashboard (unique URL, name, etc.)
  • getDatasources ( string dashboard )
    Gets all datasources related to a dashboard.
  • reload ( string dashboard )
    Reloads all pending datasources belonging to a dashboard. Pending datasources are datasources which have files that have not been analysed or reloaded yet.

datasource

  • createJSONFragment ( string dashboard string datasource data data , [ string fragmentName ] )
    Adds a new fragment to a specified datasource. The data will be sent to the fragment through a JSON string.
  • delete ( string dashboard string datasource )
    Deletes a specified datasource. All data belonging to this datasource will be removed from the dashboard data.
  • deleteData ( string dashboard string datasource data deleteParams )
    Deletes specific data extracts from a datasource. Lines to delete are specified through a JSON string. Deleted data can concern different fragments at once.
  • deleteFragment ( string dashboard string datasource string fragmentName )
    Deletes a specific fragment from a datasource. All lines belonging to the fragment will be removed from the dashboard data.
  • reload ( string dashboard string datasource , [ string file ] )
    Reloads all or selected pending files belonging to the datasource.

sheet

  • duplicate ( string dashboard string sheetName )
    Duplicates all sheets having the given sheet name.

dashboard

createDatasource

delete

duplicate

copyData

get

getDatasources

reload

/dashboard/createDatasource

Creates a new empty datasource in the dashboard using the provided datasource name. Returns the unique code of the created datasource.
Try it on the API playground >>

Example Request JSON

{ "dashboard" : "d1d528aad3d7a814187f7e3d31c02d0d", "datasourceName" : "Sales data" }

Example Response JSON

{"response":{"meta":{"responseSuccess":"true","responseTime":"2013-03-12T17:11:01+00:00","resultCount":"1"},"resultStatus":{"status":"success"},"results":{"element":{"datasourceName":"New datasource","datasourceUniqueCode":"23fe22c3e6a1ee7a06065e3b589324c9"}}}}

Example Error Response JSON

{"response":{"meta":{"responseSuccess":"true","responseTime":"2013-03-13T11:25:06+00:00","resultCount":"1"},"resultStatus":{"status":"error","errorCode":"invalidDashboardKey","errorMessage":"Invalid dashboard key."},"results":[]}}
Parameters
dashboard * string A valid dashboard API key.
datasourceName string The name of the datasource. Defaults to "New datasource". Optional.
lb bool Adds linebreaks to the XML string. Applies to XML strings only. Defaults to false. Optional.
format string Output format of the response. See response formats for available options. Defaults to xml. Optional.
Errors
missingDashboardKey Missing dashboard API key.
createImpossible Could not create datasource.
invalidJSON JSON string not valid.
limitedTo5Datasources You are currently using the FREE plan which is limited to 5 datasources per dashboard. Please upgrade your account to have UNLIMITED datasources.
databaseTransactionFailed Database transaction failed.
unknownError Unknown error.

Back to top

/dashboard/delete

Deletes the dashboard and all related elements.
Try it on the API playground >>

Example Request JSON

{ "dashboard" : "d1d528aad3d7a814187f7e3d31c02d0d" }

Example Response JSON

{"response":{"meta":{"responseSuccess":"true","responseTime":"2013-03-12T20:32:57+00:00","resultCount":"1"},"resultStatus":{"status":"success"},"results":{"element":{"elementsDeleted":"true"}}}}

Example Error Response JSON

{"response":{"meta":{"responseSuccess":"true","responseTime":"2013-03-13T11:25:06+00:00","resultCount":"1"},"resultStatus":{"status":"error","errorCode":"invalidDashboardKey","errorMessage":"Invalid dashboard key."},"results":[]}}
Parameters
dashboard * string A valid dashboard API key.
lb bool Adds linebreaks to the XML string. Applies to XML strings only. Defaults to false. Optional.
format string Output format of the response. See response formats for available options. Defaults to xml. Optional.
Errors
missingDashboardKey Missing dashboard API key.
deletingImpossible Could not delete dashboard.
databaseTransactionFailed Database transaction failed.
unknownError Unknown error.

Back to top

/dashboard/duplicate

Duplicates the dashboard and all its related elements (sheets, dashboard elements,...). Optionally it is possible to duplicate the data of the dashboard and the user rights. If the dashboard data is not duplicated, datasources will be duplicated but will not contain any files and the charts will remain empty.
Try it on the API playground >>

Example Request JSON

{ "dashboard" : "d1d528aad3d7a814187f7e3d31c02d0d", "duplicateData" : "true", "duplicateUsers" : "false", "name" : "Sales dashboard" }

Example Response JSON

{"response":{"meta":{"responseSuccess":"true","responseTime":"2013-03-12T20:36:51+00:00","resultCount":"1"},"resultStatus":{"status":"success"},"results":{"element":{"dashboardAccessUrl":"8a6fa37140e691a1a61c51144dcc1a4e","dashboardApiKey":"a1cadba74812e0820e809dcce2286494"}}}}

Example Error Response JSON

{"response":{"meta":{"responseSuccess":"true","responseTime":"2013-03-13T11:25:06+00:00","resultCount":"1"},"resultStatus":{"status":"error","errorCode":"invalidDashboardKey","errorMessage":"Invalid dashboard key."},"results":[]}}
Parameters
dashboard * string A valid dashboard API key.
duplicateData bool Set this to true to duplicate all the data related to the dashboard. Defaults to false. Optional.
duplicateUsers bool Set this to true to duplicate dashboard related user rights. Defaults to false. Optional.
name string The name you'd like to give to the new dashboard. Defaults to "Copy of NAME_OF_DASHBOARD_TO_DUPLICATE". Optional.
lb bool Adds linebreaks to the XML string. Applies to XML strings only. Defaults to false. Optional.
format string Output format of the response. See response formats for available options. Defaults to xml. Optional.
Errors
missingDashboardKey Missing dashboard API key.
invalidJSON JSON string not valid.
duplicateFailed Duplicate process failed.
insufficientCalculationPower Not enough storage.
databaseTransactionFailed Database transaction failed.
unknownError Unknown error.

Back to top

/dashboard/copyData

Copies all the datasources and data belonging to a specified dashboard (source dashboard) to another dashboard (target dashboard). All the data of the target dashboard will be replaced by the data of the source dashboard. The sheets and elements belonging to the target dashboard will not be modified.
Try it on the API playground >>

Example Request JSON

{ "dashboard" : "d1d528aad3d7a814187f7e3d31c02d0d", "targetDashboard" : "aa1418a80d1d528d3d37f7e71c02dd3d" }

Example Error Response JSON

{"response":{"meta":{"responseSuccess":"true","responseTime":"2013-03-13T11:25:06+00:00","resultCount":"1"},"resultStatus":{"status":"error","errorCode":"invalidDashboardKey","errorMessage":"Invalid dashboard key."},"results":[]}}
Parameters
dashboard * string A valid dashboard API key.
targetDashboard * string The API key of the target dashboard. Mandatory.
lb bool Adds linebreaks to the XML string. Applies to XML strings only. Defaults to false. Optional.
format string Output format of the response. See response formats for available options. Defaults to xml. Optional.
Errors
missingDashboardKey Missing dashboard API key.
invalidJSON JSON string not valid.
copyFailed Copy process failed.
missingOwnerRights Source and target dashboard must have the same owner.
insufficientCalculationPower Not enough storage.
copyImpossible Could not copy data.
databaseTransactionFailed Database transaction failed.
unknownError Unknown error.

Back to top

/dashboard/get

Gets information about the dashboard (unique URL, name, etc.)
Try it on the API playground >>

Example Request JSON

{ "dashboard" : "d1d528aad3d7a814187f7e3d31c02d0d" }

Example Response JSON

{"response":{"meta":{"responseSuccess":"true","responseTime":"2013-03-12T20:54:19+00:00","resultCount":"1"},"resultStatus":{"status":"success"},"results":{"element":{"dashboardName":"Global sales","dashboardAccessUrl":"1eb4cb10a9ff786c84767eeead01f6f1","dashboardLastModificationDateTime":"2013-02-25 00:00:00","isPublic":"true","dashboardApiKey":"b5469a6695444e2b4734bd9538633715","isRemoteDatabaseDashboard":"false","totalDataAmount":"115500"}}}}

Example Error Response JSON

{"response":{"meta":{"responseSuccess":"true","responseTime":"2013-03-13T11:25:06+00:00","resultCount":"1"},"resultStatus":{"status":"error","errorCode":"invalidDashboardKey","errorMessage":"Invalid dashboard key."},"results":[]}}
Parameters
dashboard * string A valid dashboard API key.
lb bool Adds linebreaks to the XML string. Applies to XML strings only. Defaults to false. Optional.
format string Output format of the response. See response formats for available options. Defaults to xml. Optional.
Errors
missingDashboardKey Missing dashboard API key.
databaseTransactionFailed Database transaction failed.
unknownError Unknown error.

Back to top

/dashboard/getDatasources

Gets all datasources related to a dashboard.
Try it on the API playground >>

Example Request JSON

{ "dashboard" : "d1d528aad3d7a814187f7e3d31c02d0d" }

Example Response JSON

{"response":{"meta":{"responseSuccess":"true","responseTime":"2013-03-12T21:05:40+00:00","resultCount":"2"},"resultStatus":{"status":"success"},"results":{"element":[{"datasourceName":"State results","datasourceUniqueCode":"ee7f19893272578bb9a68889df6dd029","dataAmount":"10520","numberOfRows":"51","creationDateTime":"2012-11-05 22:48:16.081734","lastImportDateTime":"2012-11-05 23:15:08.677568","isPendingDataImport":"false","isDatabaseDatasource":"false","isFileDatasource":"true","isWebserviceDatasource":"false","isExternalDatabaseDatasource":"false"},{"datasourceName":"Demographic data","datasourceUniqueCode":"54c1d6f24c8b1e5f0455c27a8a8a7922","dataAmount":"0","numberOfRows":"n.a.","creationDateTime":"2013-03-12 21:07:13.200589","lastImportDateTime":"n.a.","isPendingDataImport":"false","isDatabaseDatasource":"false","isFileDatasource":"true","isWebserviceDatasource":"false","isExternalDatabaseDatasource":"false"}]}}}

Example Error Response JSON

{"response":{"meta":{"responseSuccess":"true","responseTime":"2013-03-13T11:25:06+00:00","resultCount":"1"},"resultStatus":{"status":"error","errorCode":"invalidDashboardKey","errorMessage":"Invalid dashboard key."},"results":[]}}
Parameters
dashboard * string A valid dashboard API key.
lb bool Adds linebreaks to the XML string. Applies to XML strings only. Defaults to false. Optional.
format string Output format of the response. See response formats for available options. Defaults to xml. Optional.
Errors
missingDashboardKey Missing dashboard API key.
databaseTransactionFailed Database transaction failed.
unknownError Unknown error.

Back to top

/dashboard/reload

Reloads all pending datasources belonging to a dashboard. Pending datasources are datasources which have files that have not been analysed or reloaded yet.
Try it on the API playground >>

Example Request JSON

{ "dashboard" : "d1d528aad3d7a814187f7e3d31c02d0d" }

Example Error Response JSON

{"response":{"meta":{"responseSuccess":"true","responseTime":"2013-03-13T11:25:06+00:00","resultCount":"1"},"resultStatus":{"status":"error","errorCode":"invalidDashboardKey","errorMessage":"Invalid dashboard key."},"results":[]}}
Parameters
dashboard * string A valid dashboard API key.
lb bool Adds linebreaks to the XML string. Applies to XML strings only. Defaults to false. Optional.
format string Output format of the response. See response formats for available options. Defaults to xml. Optional.
Errors
missingDashboardKey Missing dashboard API key.
runningAnalysis An analysis of your data is already running. Please try again later.
noPendingDatasources No pending datasources detected.
loadingImpossible Could not load data.
databaseTransactionFailed Database transaction failed.
unknownError Unknown error.

Back to top

datasource

createJSONFragment

delete

deleteData

deleteFragment

reload

/datasource/createJSONFragment

Adds a new fragment to a specified datasource. The data will be sent to the fragment through a JSON string.
Try it on the API playground >>

Example Request JSON

{ "dashboard" : "d1d528aad3d7a814187f7e3d31c02d0d", "datasource" : "23se22c3e6see7a06065esb58f324c9", "data" : [{"BilllingID": "1", "ProductID": "laptop", "ProductLabel": "Laptop", "Amount":"799", "Currency":"USD", "Date":"2012-10-08"},{"BilllingID":"2", "ProductID":"screen", "ProductLabel":"Screen", "Amount":"229", "Currency":"USD", "Date":"2012-10-28"},{"BilllingID":"3", "ProductID":"laptop", "ProductLabel":"Laptop", "Amount":"669", "Currency":"USD", "Date":"2012-11-30"}], "fragmentName" : "sales_20121001_france" }

Example Response JSON

{"response":{"meta":{"responseSuccess":"true","responseTime":"2013-03-12T21:59:02+00:00","resultCount":"1"},"resultStatus":{"status":"success"},"results":{"element":{"elementsCreated":"true","fragmentName":"sales_spain_20121222"}}}}

Example Error Response JSON

{"response":{"meta":{"responseSuccess":"true","responseTime":"2013-03-13T11:25:06+00:00","resultCount":"1"},"resultStatus":{"status":"error","errorCode":"invalidDashboardKey","errorMessage":"Invalid dashboard key."},"results":[]}}
Parameters
dashboard * string A valid dashboard API key.
datasource * string The unique key of the datasource. Mandatory.
data * data A JSON string containing the data to send. To read more about the data format click here. Mandatory.
fragmentName string The unique name of the bucket to which the data will be attached. If this parameter is missing a unique name will be created and can be fetched from the response. Optional.
lb bool Adds linebreaks to the XML string. Applies to XML strings only. Defaults to false. Optional.
format string Output format of the response. See response formats for available options. Defaults to xml. Optional.
Errors
missingDashboardKey Missing dashboard API key.
invalidDatasourceKey Invalid datasource key.
invalidJSON JSON string not valid.
failedToCallDataConverter Can't call data converter.
failedDataReading Can't read data.
runningAnalysis An analysis of your data is already running. Please try again later.
noServerResponse No server response.
failedDataConversion The error message is customized depending on the data conversion problem that occured.
datasourceNotInDashboard This datasource does not belong to this dashboard.
databaseTransactionFailed Database transaction failed.
unknownError Unknown error.

Back to top

/datasource/delete

Deletes a specified datasource. All data belonging to this datasource will be removed from the dashboard data.
Try it on the API playground >>

Example Request JSON

{ "dashboard" : "d1d528aad3d7a814187f7e3d31c02d0d", "datasource" : "23se22c3e6see7a06065esb58f324c9" }

Example Response JSON

{"response":{"meta":{"responseSuccess":"true","responseTime":"2013-03-12T22:00:31+00:00","resultCount":"1"},"resultStatus":{"status":"success"},"results":{"element":{"dataDeleted":"true"}}}}

Example Error Response JSON

{"response":{"meta":{"responseSuccess":"true","responseTime":"2013-03-13T11:25:06+00:00","resultCount":"1"},"resultStatus":{"status":"error","errorCode":"invalidDashboardKey","errorMessage":"Invalid dashboard key."},"results":[]}}
Parameters
dashboard * string A valid dashboard API key.
datasource * string The unique key of the datasource. Mandatory.
lb bool Adds linebreaks to the XML string. Applies to XML strings only. Defaults to false. Optional.
format string Output format of the response. See response formats for available options. Defaults to xml. Optional.
Errors
missingDashboardKey Missing dashboard API key.
deleteDataFailed Could not delete data.
invalidDatasourceKey Invalid datasource key.
invalidJSON JSON string not valid.
databaseTransactionFailed Database transaction failed.
unknownError Unknown error.

Back to top

/datasource/deleteData

Deletes specific data extracts from a datasource. Lines to delete are specified through a JSON string. Deleted data can concern different fragments at once.
Try it on the API playground >>

Example Request JSON

{ "dashboard" : "d1d528aad3d7a814187f7e3d31c02d0d", "datasource" : "23se22c3e6see7a06065esb58f324c9", "deleteParams" : {"name":"Bob", "age":24} }

Example Response JSON

{"response":{"meta":{"responseSuccess":"true","responseTime":"2013-03-12T22:03:59+00:00","resultCount":"1"},"resultStatus":{"status":"success"},"results":{"element":{"elementsDeleted":"true"}}}}

Example Error Response JSON

{"response":{"meta":{"responseSuccess":"true","responseTime":"2013-03-13T11:25:06+00:00","resultCount":"1"},"resultStatus":{"status":"error","errorCode":"invalidDashboardKey","errorMessage":"Invalid dashboard key."},"results":[]}}
Parameters
dashboard * string A valid dashboard API key.
datasource * string The unique key of the datasource. Mandatory.
deleteParams * data A JSON string containing the specifications of the data to delete. To read more about the format of this JSON string click here. Mandatory.
lb bool Adds linebreaks to the XML string. Applies to XML strings only. Defaults to false. Optional.
format string Output format of the response. See response formats for available options. Defaults to xml. Optional.
Errors
missingDashboardKey Missing dashboard API key.
invalidDatasourceKey Invalid datasource key.
invalidJSON JSON string not valid.
failedToCallDataConverter Can't call data converter.
failedDataReading Can't read data.
runningAnalysis An analysis of your data is already running. Please try again later.
noServerResponse No server response.
databaseTransactionFailed Database transaction failed.
unknownError Unknown error.

Back to top

/datasource/deleteFragment

Deletes a specific fragment from a datasource. All lines belonging to the fragment will be removed from the dashboard data.
Try it on the API playground >>

Example Request JSON

{ "dashboard" : "d1d528aad3d7a814187f7e3d31c02d0d", "datasource" : "23se22c3e6see7a06065esb58f324c9", "fragmentName" : "sales_20121001_france" }

Example Response JSON

{"response":{"meta":{"responseSuccess":"true","responseTime":"2013-03-12T22:04:58+00:00","resultCount":"1"},"resultStatus":{"status":"success"},"results":{"element":{"fragmentDeleted":"true"}}}}

Example Error Response JSON

{"response":{"meta":{"responseSuccess":"true","responseTime":"2013-03-13T11:25:06+00:00","resultCount":"1"},"resultStatus":{"status":"error","errorCode":"invalidDashboardKey","errorMessage":"Invalid dashboard key."},"results":[]}}
Parameters
dashboard * string A valid dashboard API key.
datasource * string The unique key of the datasource. Mandatory.
fragmentName * string The complete fragment name (can be file name + extension, ex. myfile.csv, if the fragment was created using a file upload) of the fragment to delete. Mandatory.
lb bool Adds linebreaks to the XML string. Applies to XML strings only. Defaults to false. Optional.
format string Output format of the response. See response formats for available options. Defaults to xml. Optional.
Errors
missingDashboardKey Missing dashboard API key.
invalidDatasourceKey Invalid datasource key.
invalidJSON JSON string not valid.
deleteDataFailed Could not delete data.
fragmentNotFound Data fragment not found.
databaseTransactionFailed Database transaction failed.
unknownError Unknown error.

Back to top

/datasource/reload

Reloads all or selected pending files belonging to the datasource.
Try it on the API playground >>

Example Request JSON

{ "dashboard" : "d1d528aad3d7a814187f7e3d31c02d0d", "datasource" : "23se22c3e6see7a06065esb58f324c9", "file" : "sales_data_01_2012.csv" }

Example Error Response JSON

{"response":{"meta":{"responseSuccess":"true","responseTime":"2013-03-13T11:25:06+00:00","resultCount":"1"},"resultStatus":{"status":"error","errorCode":"invalidDashboardKey","errorMessage":"Invalid dashboard key."},"results":[]}}
Parameters
dashboard * string A valid dashboard API key.
datasource * string The unique key of the datasource. Mandatory.
file string The complete file name (file name + extension, ex. myfile.csv) of the file to reload. If this parameter is missing all pending files will be reloaded. Optional.
lb bool Adds linebreaks to the XML string. Applies to XML strings only. Defaults to false. Optional.
format string Output format of the response. See response formats for available options. Defaults to xml. Optional.
Errors
missingDashboardKey Missing dashboard API key.
invalidDatasourceKey Invalid datasource key.
invalidJSON JSON string not valid.
failedToCallDataConverter Can't call data converter.
failedDataReading Can't read data.
runningAnalysis An analysis of your data is already running. Please try again later.
noServerResponse No server response.
dataLoadError [Message depending on error type]
databaseTransactionFailed Database transaction failed.
unknownError Unknown error.

Back to top

sheet

duplicate

/sheet/duplicate

Duplicates all sheets having the given sheet name.
Try it on the API playground >>

Example Request JSON

{ "dashboard" : "d1d528aad3d7a814187f7e3d31c02d0d", "sheetName" : "Sales per country" }

Example Response JSON

{"response":{"meta":{"responseSuccess":"true","responseTime":"2013-03-12T22:13:41+00:00","resultCount":"1"},"resultStatus":{"status":"success"},"results":{"element":{"newSheetName":"Copy of Sales analysis"}}}}

Example Error Response JSON

{"response":{"meta":{"responseSuccess":"true","responseTime":"2013-03-13T11:25:06+00:00","resultCount":"1"},"resultStatus":{"status":"error","errorCode":"invalidDashboardKey","errorMessage":"Invalid dashboard key."},"results":[]}}
Parameters
dashboard * string A valid dashboard API key.
sheetName * string The name of the sheet to duplicate. If several sheets have the same name all sheets having the specified name will be duplicated. Mandatory.
lb bool Adds linebreaks to the XML string. Applies to XML strings only. Defaults to false. Optional.
format string Output format of the response. See response formats for available options. Defaults to xml. Optional.
Errors
missingDashboardKey Missing dashboard API key.
duplicateFailed Could not duplicate sheet.
invalidJSON JSON string not valid.
missingSheetName Missing sheet name.
databaseTransactionFailed Database transaction failed.
unknownError Unknown error.

Back to top