How to use our API

What is an API?

The term API stands for Application Programming Interface. It’s a communication protocol between a client and a server intended to simplify the implementation of each others data. The communication will be in a specified format or initiate a defined action, as to fit perfectly in each others software.

An API Key is the unique identifier used to authenticate a user or a program that is calling upon the API to share its information with.


What does the API mean for users of our Platform?

It means you can use the API to easily send your own data to be implemented with the data already on our platform. This could be data deriven from your ERP or CRM system, or from your sensors and measurement systems.


How to use our API and API key

  1. Generate an API Key

    Since the API is in a public beta, the API-key has to be requested via mail at help@calculus.group. You can contact us by sending an email with the subject “Calculus API Key Request“. Let us know in the mail for which company you need the API key and what you will be using it for

    Please note! If the API key were to get compromised, you can send us an email on the same address to revoke the key.
  2. Use the API
    The API endpoint to use when posting data to our platform is “https://api.calculus.group/General/PostData“. Calls are done using the Http-action “POST”.

    2.1 Query parameters
    api-version



    The version of the API you want to call, v1.0 is deprecated at the moment. 2.0 is currently the way to go. Use : api-version=2.0


    A typical call would be a POST call to ” https://api.calculus.group/General/PostData?api-version=2.0

    2.2 Headers
    In the headers we send the API Key to the cloud to authenticate your device.
    CalculusApiKey  Use the API key you got in step 1 to authenticate to the API

    2.3 JSON-Body
    The body of the request is formatted in JSON. Using ‘check-deltas‘ and ‘reset-deltas‘ are used when values can overflow and reset to 0. If you want the correct cumulative values this can be used to calculate these in our backend. Contact us for more information on how to implement this at help@calculus.group.

    The following values can be set:
    device Devicename of the gateway you want to add data to. When the devicename doesn’t exist, the gateway is added automatically. Use the prefix we provide you together with the API key in front of your chosen device, in the following format:
    prefix_gateway”
    timestamp Seconds since January 1, 1970 (epoch)
    check-deltas
    [Currently only available after flagging a measurementpath as delta. Contact us for more information on help@calculus.group]
    reset-deltas [Currently only available after flagging a measurementpath as delta. Contact us for more information on help@calculus.group]
    measurements An array of measurementvalues you want to add. This can have either a value, a stringvalue or both.
    path string, the measurementname. This will be used together with the devicename to form the complete measurementpath. For example with a devicename of “prefix_TestDevice” and a path of “Testpath” the full measurementpath will be “prefix_TestDevice|Testpath” for use in the portal. No spaces or special characters are allowed besides “.”, “_”, “-” and “|”
    value double, value related to the path
    stringValue string, max 50 characters, value related to the path

    Example JSON body:
    { "device":"prefix_TestDevice", "check-deltas":true, "reset-deltas":true, "timestamp":1573206752, "measurements":[ { "path": "measurement_1", "value": 1 }, { "path": "measurement-2", "stringValue":"OFF" }, { "path": "temp|measurement.3", "value": 9.4, "stringValue":"BROKEN" }, { "path": "temp|measurement.4", "value": 11.4, "stringValue":"OVERLOAD" } ] } 


Updated on 7 April 2020

Was this article helpful?

Leave a Comment