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.
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.
|
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: "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.
|
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. 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 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.
|
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"
}
]
}
Was this article helpful?
- How to use our API
- I have a question, what can Calculus do for me?