Using our Data API


Please watch our tutorial video:


With our app, you can  save  and  export  measurements. However, sometimes you need more advanced access than this. For instance, if you would like to perform the export in an automated way.

For this reason, we have created a data access API (application programming interface). It allows you to access data using scripts and obtain detailed insights into your processes.

The documentation and source code examples can be found in our Gitlab repository  https://gitlab.com/matohascience/matoha-api-docs  .

The Data API is currently provided free of charge but we reserve the right to make it subject to a (reasonable) paid subscription agreement in the future, as we develop our Cloud interface. For further information, please contact us with the details of your planned use - we might be able to give you guarantees of perpetual free use depending on your use case.


A quick tutorial

Step 1 - Obtain API credentials

Please open our app, then click on My account and you should see the screen as per the screenshot below. Please press the "Generate API key" button and then use the yellow copy buttons to copy the credentials from the app. Anyone with the access to your user ID and API key will have access to your data so please keep it secure!

   


Step 2 Try out API demo

Please visit https://matohascience.gitlab.io/matoha-api-docs/ . Then, enter the user ID and API key you have obtained from the app into the interface.  Now you should be able to perform various actions, such as retrieve the collections, data etc.



In each case, the example will generate a "Request URL", such as 

            https://api.matoha.com/v1/get_collections?supervisor=1&user=YOUR USER ID HERE&api_key=YOUR API KEY HERE
             
          

This URL (link) is relatively human-readable and contains important instructions for the API:

  • address of the server (https://api.matoha.com/)

  • the API function to call (v1/get_collections)

  • the function parameters (?supervisor=1)

  • and your credentials (user=YOUR USER ID HERE&api_key=YOUR API KEY HERE)

This URL contains the various parameters which can be used to request specific types of data etc - the full documentation is here https://gitlab.com/matohascience/matoha-api-docs .


Step 3 Next steps

How can you use the API? Here are a few ideas:

  • use the Get Data function to export your data in a CSV or JSON format. The data in this format can be then analysed in Excel or all kinds of business intelligence software, such as Tableau. The link the example makes for you (such as https://api.matoha.com/v1/get_data? ....) is "permanent", ie you can visit it every time you would like your data exported.

  • look at our Python and Javascript examples for how to use the API directly in your scripts.


Any questions? Please do get in touch, we would love to help you!