How to use our API

What is an API?

The term API stands for Application Programming Interface. It is a communication protocol designed to simplify the exchange of data between a client and a server. Communication follows a strict format or initiates a specific action, ensuring that the two components work together seamlessly.

An API key is a unique identifier used to authenticate a user or a program that calls upon the API.

What does the API mean for users of our platform?

This means you can use the API to easily send data to our platform or retrieve data from it.

Send your own data to combine it with the data already on our platform. This could be data from an ERP or CRM system, or from sensors and measurement systems. You can also retrieve data to use in your own application.

How do you use our API and API key?

Step 1: create an API key

Since the API is currently in public beta, you must request the API key by emailing help@calculus.group. Please contact us by sending an email with the subject line “Request API key for Calculus.” In the email, let us know which company you need the API key for and what you plan to use it for.

Please note!
If the API key is compromised, you can send us an email at the same address to revoke the key.

Step 2: use the API to retrieve data

Using the API, you can retrieve data for all assets associated with the company to which the API key belongs. The API endpoint for retrieving data is “https://api.calculus.group/asset/{key}”. Replace {key} with the asset’s unique identifier. Requests are made using the HTTP “GET” method.

Parameters

Name	Description
epochStart	The start of the time series for which you need data. The date/time format used is “Epoch,” the UNIX timestamp. Visit https://www.epochconverter.com/ for conversion tools to and from Epoch. If you use this parameter, you must always use it in conjunction with the “epochEnd” parameter. If not used, the default is the last 24 hours.
epochEnd	The end of the time series for which you need data. The date/time format used is “Epoch,” the UNIX timestamp. Visit https://www.epochconverter.com/ for conversion tools to and from Epoch. If you use this parameter, you must always use it in conjunction with the “epochStart” parameter. If not used, the default is the last 24 hours.

Name

Description

epochStart

The start of the time series for which you need data.

The date/time format used is “Epoch,” the UNIX timestamp. Visit https://www.epochconverter.com/ for conversion tools to and from Epoch.

If you use this parameter, you must always use it in conjunction with the “epochEnd” parameter.

If not used, the default is the last 24 hours.

epochEnd

The end of the time series for which you need data.

The date/time format used is “Epoch,” the UNIX timestamp. Visit https://www.epochconverter.com/ for conversion tools to and from Epoch.

If you use this parameter, you must always use it in conjunction with the “epochStart” parameter.

If not used, the default is the last 24 hours.

Header

The header contains the API key to the Calculus platform to authenticate your device.

Name	Description
CalculusApiKey	Use the API key you received in step 1 to authenticate with the API.

Body

The body of the request is always in JSON format.

Step 3: use the API to post data

The API endpoint for posting data to our platform is “https://api.calculus.group/General/PostData”. Requests are made using the HTTP “POST” method.

Name	Description
api-version	The version of the API you want to call. Version 1.0 is deprecated; version 2.0 is currently the recommended version. Use “api-version=2.0”.

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

JSON format

The body of the request is always in JSON format. “check-deltas” and “reset-deltas” are used when values may overflow and need to be reset to 0. If you want the correct cumulative values, this can be used to calculate them in our backend. Please contact us at help@calculus.group for more information on how to implement this.

The following values can be set:

Name	Description
device	The device name of the gateway to which you want to add data. If it does not exist, the gateway will be added automatically. Use the prefix we provide along with the API key for your chosen device, in the following format: “prefix_gateway”.
timestamp	Seconds since January 1, 1970 (epoch).
check-deltas	Currently available only after marking a measurement path as a delta. Please contact us at help@calculus.group for more information.
reset-deltas	Currently available only after marking a measurement path as a delta. Please contact us at help@calculus.group for more information.
	An array of measurement values that you want to add. It can contain a numeric value, a string value, or both.
measurements	path	Data type “string”, the measurement name. This will be used together with the device name to form the full measurement path. For example, with a device name of “prefix_TestDevice” and a path of “Testpath”, the full measurement path will be “prefix_TestDevice\|Testpath”. Except for “.”, “_”, “-”, and “\|”, no spaces or special characters are allowed.
	value	Data type “double”, value associated with the path.
	stringValue	Data type “string”, maximum 50 characters, value associated with the path.

JSON example

{
    "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"
            }
        ]
}