GUIDES
Getting Started
• What is Marple?
• Setup Marple
• First steps
• Create a team
Using Marple
Data Types
• Data Formats
• Data Points
DOCUMENTATION
Data Library
Analysis
InfluxDB
Projects
Workspaces
Plot types
Calculated signals
Settings
For developers
By Category > For developers
API Documentation
Use the Marple API

Marple Python SDK

We created an SDK for Python that makes it easier to use the API. Install the marpledata module using:
pip install marpledata

Usage

First, setup a Marple connection.
from marple import Marple
m = Marple(ACCESS_TOKEN)
You can find your personal access token in your account settings.

Uploading data can be done in various ways:
  • Upload a file using the SDK
  • A pandas dataframe
  • Write data in chunks
source_id = m.upload_data_file(file_path, marple_folder, metadata={})
source_id = m.upload_data_pandas(dataframe, target_name, marple_folder, metadata={})
m.add_data(data_dict)
source_id = m.send_data(target_name, marple_folder, metadata={})
More details can be found at https://pypi.org/project/marpledata/

API Guide

This guide will show the essential steps for connecting to and using the API for common tasks. At the bottom of this page you can find the full API reference.

1 Connecting to the API

1.1 URL

The API is hosted at https://app.marpledata.com/api/v1 on the Marple cloud, or .../api/v1 on your self-managed server. All API endpoints are relative to this URL. E.g. the /version endpoint should be called as https://app.marpledata.com/api/v1/version. Always make sure that you use https for secure communication.

1.2 Authentication

Since 2.2.0 Marple instead uses Access Tokens provided by Auth0 and other Identity providers (e.g. Google account)  for authentication.  To generate such an Access Token you can either:
Pass this token in the Authorization header in Bearer token format, it will be valid for 30 days.
Authorization: Bearer <access-token>

1.3 Passing Arguments and Parsing Responses

There are two ways of passing arguments to an endpoint: either encoded as key-value pairs in the URL or encoded as JSON in the body of the request. This depends on the endpoint, in general GET requests will use URL encoding, while POST requests will use JSON encoding. The full specification of all endpoints can be found at the bottom of the page. Here is some example code of both methods in Python:
r = requests.get(f'{api_url}/sources/lookup', headers=auth_header, params={'path': path})

body = {'path': '/', 'new_folder_name': 'new_folder'}
r = requests.post(f'{api_url}/library/folder/add', headers=auth_header, json=body)
Requests will always return data as JSON with the following structure:
{"request_time": time, "message": data}
It will contain both the time the server has taken to process the request and the actual output. Decode and access the message key to extract the result:
response = requests.get(f'{api_url}/version', headers=auth_header)
version = response.json()['message']
print(version)  # 2.1.6

2 Uploading and Importing Files

In Marple files are uploaded onto a file server and then parsed into our database which we call 'importing'. Once a file has been imported into the database it is referred to as a 'source'.

Steps

  1. POST /library/file/upload
    Upload a file onto the file server.
    URL query parameters:
    • path: the path to the directory on the file server where the file should be uploaded
    File body parameters:
    • file: the file contents
    => Returns "OK", and confirms the path where the file is uploaded
    ‍
    Example:
    #Setup
    api_url = 'https://app.marpledata.com/api/v1'
    endpoint = '/library/file/upload'
    token = '...'
    auth_header = {'Authorization': f'Bearer {token}'}
    ‍
    #Arguments
    files = {'file': open('myfile.csv', 'rb')}
    target_dir = '/'  # file server root dir
    target_dir = '/sub_dir' # or a subdirectory

    #Request
    r = requests.post(f'{base_url}{endpoint}', headers=auth_header,
                     params={'path': target_dir}, files=files)

    #Response
    r.json()['message'] == {'status': 'OK', 'path': 'sub_dir'}
  2. POST /library/file/import
    Start importing a file into the database
    JSON body parameters:
    • path: the path to where the file is located on the server
    • plugin: the plugin to be used for imporing the file
    => Returns the source_id of the file in the database, and the metadata associated with the file
    ‍
    Example:
    endpoint = '/library/file/import'
    path = '/sub_dir/myfile.csv'
    plugin = 'csv_plugin'

    r = requests.post(f'{base_url}{endpoint}', headers=auth_header,
                      json={'path': path, 'plugin': plugin})

    r.json()['message'] == {
      'source_id': 1,
       'metadata': [
           {'name' : 'key1', 'value': 'value1'},
           {'name' : 'key2', 'value': 'value2'}
       ]
    }
  3. GET /sources/status
    Monitor the progression of the file import process
    URL query parameters:
    • id: Source id or array of source ids for which to request the status.
    To pass an array as a query parameter use the following syntax:
    api_url/sources/status?id=1,2,3,...
    => Returns an array of status codes
    ‍
    Example:
    endpoint = '/sources/status'
    source_id = 1

    r = requests.post(f'{base_url}{endpoint}', headers=auth_header,
                      params={'id': source_id})

    r.json()['message'] == {[{
      'source_id': 1,
       'status': 100
    }]}

3 Adding Metadata

Metadata can be manipulated using the /library/metadata endpoints. Metadata is always coupled to files using the 'source id' and not the file name. The source id associated with a file can be found using the  /sources/lookup endpoint.

Steps

  1. GET /sources/lookup
    Get source id associated with file.
    URL query parameters:
    • path: full filepath of file to lookup
    => Returns the source_id of the file
    ‍
    Example:
    endpoint = '/sources/lookup'
    path = '/sub_dir/myfile.csv'

    r = requests.post(f'{base_url}{endpoint}', headers=auth_header,
                      params={'path': path})
  2. POST /library/metadata
    Add metadata to a source
    JSON body parameters:
    • source_id: the source to add the metadata to
    • path: (optional) If the file does not yet have a source_id it can be referenced by its path. This function will return the source id assigned to the file in this case
    • metadata: Key-value pairs to add to metadata. Dates must be UTC timestamps in seconds. This dictionary has the following format:
      [  
          {    
              "name": "timestamp_modified",  
              "value": 1625751149 // UTC timestamp in seconds  
          },
          {   "name": "department",    "value": "Testing"  },
         ...
      ]
    => Returns source id and "OK" message
    ‍
    Example:

    source_id = 1
    metadata = [{'name': 'Author', 'value': 'Jan Scheers'}]

    r = requests.post(f'{base_url}{endpoint}', headers=auth_header,
                      json={'source_id': source_id, 'metadata': metadata})
    endpoint = '/library/metadata'

4 Sharing Projects and Sources

A project can be shared using the /library/share endpoints. Make sure to first save the project in the app before using these endpoints.
  1. POST /library/share/new
    Generate a new share link id
    JSON body parameters
    • workbook_name: name of the project you wish to share
    • source_ids: sources to include in the share
    => Returns new share id
    ‍
    Example:
    endpoint = '/library/share/new'
    name = 'example'
    source_ids = [1,2,3]
    ‍
    r = requests.post(f'{base_url}{endpoint}', headers=auth_header,
                      json={'workbook_name': name, 'source_ids': source_ids})
  2. POST /library/share/<share_id>/add
    Add data to share id
    JSON body parameters:
    • workbook_name: change project for this share
    • source_ids: Source ids to add to share
    => Returns new share id with updated content
    ‍
    Example:
    share_id = '1234567890abcdef'
    endpoint = f'/library/share/{share_id}/add'
    source_ids = [4,5,6]
    ‍
    r = requests.post(f'{base_url}{endpoint}', headers=auth_header,
                      json={'workbook_name': name, 'source_ids': source_ids})
  3. POST /library/share/<share_id>/link
    Generate a sharable link which opens the project with its source ids
    JSON body parameters:
    • url: (optional) set base URL for the share link
    => Returns clickable link
    ‍
    Example:
    share_id = '1234567890abcdef'
    url = 'https://yourcompany.marpledata.com'
    endpoint = f'/library/share/{share_id}/link'
    ‍
    requests.get(base_url + endpoint, auth=marple_auth, args={'url': url})
    # Returns https://yourcompany.marpledata.com/?share=1234567890abcdef

5 Administrator Privileges

Some endpoints require administrator privileges. Admin authorization is associated with the account that generated the access token. Admin access can be granted by administrators of the workspace in the 'Team' tab of the workspace settings.

6 API Example Repository

Marple maintains a public repository with an example API usecase: 🔗 https://gitlab.com/marple-public/marple-api-example
This script runs a simulated experiment, logs the data, uploads and imports it into marple and then generates a share link ready for visualisation.
In the public repository there are example scripts for both Python and MATLAB.

API Reference

Marple Swagger API Reference