Home └ API └ How to use our API

How to use our API

1

.

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. The communication will be in a strict format, or initiate a particular action, so that they complement each other perfectly.

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

2

.

What does the API mean for users of our platform?

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

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

3

.

How do you use our API and API key?

1. Create an API key creation

Since the API is in a public beta, the API key must be requested via email at help@calculus.group. You can contact us by sending an e-mail, with the subject line "Request API key for Calculus". In the email, please let us know for which company you need the API key and what you will use it for.

Please note! If the API key would be compromised, please email us at the same address to revoke the key to be revoked.

2. Use the API to obtain data

Using the API, you can retrieve data from all assets that are associated with the company to which the API key belongs. The API endpoint to retrieve data is "https://api.calculus.group/asset/{key}". Replace {key} with the unique identifier of the asset. The calls are made with the HTTP action "GET".

Parameters

epochStart

The beginning of the time series from which you need data.

The date/time format used is "Epoch," the UNIX time code. Go to https://www.epochconverter.com/ for conversion tools to and from Epoch.

If you use this parameter, it should always be used together with the parameter "epochEnd".

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

epochEnd

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

The date/time format used is "Epoch," the UNIX time code. Go to https://www.epochconverter.com/ for conversion tools to and from Epoch.

If you use this parameter, it should always be used together with the parameter "epochEnd".

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


Heads

In the headers, you send the API key to the Calculus platform to authenticate your device authenticate.

CalculusApiKey

Use the API key you got in step 1 to authenticate to the API.


JSON model

The core of the request is always in JSON format.

3. Use the API to post data

The API endpoint for posting data to our platform is "https://api.calculus.group/General/PostData". The calls are made with the HTTP action "POST".

Parameters

api version

The version of the API you want to call. Version 1.0 is obsolete, version 2.0 is currently the preferred way. Use "api-version=2.0".

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

Heads

In the headers, you send the API key to the Calculus platform to authenticate your device authenticate.

CalculusApiKey

Use the API key you got in step 1 to authenticate to the API.

4

.

JSON Model

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

The following values can be set:

device

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 that we will along with the API key for your chosen device, in the following format:

"prefix_gateway".

timestamp

Seconds since Jan. 1, 1970 (epoch).

check-delta

Currently available only after marking a measurement path as delta. Please contact us for more information at help@calculus.group.

reset deltas

Currently available only after marking a measurement path as delta. Please contact us for more information at help@calculus.group.

measurements

A array of measurement values that you want to add. This can have a value, a string value, or both.

path

Datatype "string," the measurement name. This will be used along with the device name to form the complete 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 allowed.

value

Datatype "double", value related to path.

stringValue

Datatype "string", maximum 50 characters, value related to 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"

            }

        ]

}

Add Tag

Content

Need Support?

Can’t find the answer you’re looking for? Don’t worry we’re here to help.

Ask For Help

Language Choice Disclaimer

These texts have been automatically translated using advanced AI translation tools. If you notice any inaccuracies or errors, please help us improve by sending a message to hello@calculus.group. Your feedback assists us in enhancing the quality of our multilingual documentation.