Integrations & APIs

Qatium APIs

Qatium is developing APIs and integrations to partners and data integrators. You can find them below.

Ingest API

Qatium’s Ingest API  is a REST API that allows you to send sensor data to Qatium. This allows you to be completely in control of your data, being able to change the volume, type or frequency of data you decide to send.

Start sending live data, contact Q to request a token.

The Qatium Ingest API enables you to upload external data – asset status, flow, pressure and tank level variables – to your model into Qatium.

Preparing the Data

Qatium assigns a live data point to the asset defined in the body of the request. The mapping sensor-asset should be handled before the data is sent through. Qatium does not store sensor ID, name or label information as part of a mapping to the asset.

The mapping sensor-asset should be handled as shown in the table below:

VariableMetric value in the APIAsset to associate
flowflowpipe
pressurepressurejunction
pump statusstatuspump
valve statusstatusvalve
valve settingsettingvalve
tank levelleveltank
demanddemandjunction

Please note that any information sent outside of those guidelines will be shown in the tooltips and popovers but not included in the accuracy or deviation calculations.

 

Data can be sent as a body in JSON format or as a JSON or CSV file as shown in the examples below.

1. JSON Body

Headers:

Authorization: Bearer <TOKEN>
Content-Type: application/json; charset=utf-8

Body:

[
  {
    "time": <string>,
    "asset": <string>,
    "value": <number>,
    "metric": <string>,
    "unit": <string>
  },
  ...
]

 

1.2 JSON file
Headers:

Authorization: Bearer <TOKEN>
Content-Type: multipart/form-data

Form:

Name: file
Type: file

File content:

[
  {
    "time": <string>,
    "asset": <string>,
    "value": <number>,
    "metric": <string>,
    "unit": <string>
  },
  ...
]

 

1.2 CSV file

It is mandatory to include the headers within the CSV file. The order of the headers is not important.

Headers:

Authorization: Bearer <TOKEN>
Content-Type: multipart/form-data

Form:

Name: file
Type: file

File Headers:

"time","asset","metric","unit","value","test"

File content:

"time","asset","metric","unit","value","test"
<string>,<string>,<string>,<string>,<number>,<string>
...

 

VariablesLegendFormatExample
timeThe time when the reading was taken.string

(timestamp in ISO 8601 format)

“2021-11-03T15:00:00Z”
assetThe ID of the asset associated with the reading. Take into account that the ID must be the same as the one in the GIS or INP uploaded in Qatium.string

(case should be respected)

“P-1234”
valueThe value of the readings.

Valves and pump statuses should be a number, between 0 (closed) and 1 (fully open).

Tank level minimum value is set to 0.

number 

(decimal separator must be a dot “.”)

1.7
metricThe variable of the reading value.string,
one of the following values: pressure, flow, level or status
More information in the mapping table
“flow”
unit

(Optional)

The unit of the reading value is an optional field.
The value sent will be considered as identical to the one in the model.
No unit conversion will be performed. Hence, the format list includes the unit supported by the hydraulic engine.
string, either “gpm”, “cfs”, “mgd”, “imgd”, “afd”, “lps”, “l/s”, “lpm”, “l/m”, “mld”, “cmh”, “cmd”,”mwc”, ”psi”, “ft” or “m” 

(data will not be converted, the unit should match with the one used in the model for consistency and calculation relevance)

“l/s”

 

Sending the data

1. Authentication

In order to send data to the Ingest API, you must use an auth token with the right permissions.

An authorization token and endpoint url will be provided upon request. Please provide the network ID when requesting your token. The network ID can be found in the URL when visiting the network. i.e. 1a23b45c-1a23-12a3-1a23-1234a567bc89, located in the URL: https://qatium.app/network/NetworkID/NetworkName

Please contact Q to request your token and end point URL.

2. HTTP Method

The API uses the standard HTTP method POST to append a new datapoint in Qatium.

Please note that there is currently a 20 request per minute limit and two ingest formats are accepted:

  • Body with a JSON object, we recommend limit the size of the files to 50MB.
  • Multipart/form-data with a JSON or CSV file, we recommend limit the size of the files to 1.5GB.

The API is designed for realtime and near-real time updates, for historical data uploads please contact Q.

 

Understanding the response

When sending data to the Ingest API, you will get a response.

CodeDescription
200No error
400Bad request
401Authentication token missing or invalid
403Forbidden
404Not found
413The message body is too large
429Too many requests. When over the rate limits
500Unexpected error

For more technical documentation, please visit our technical pages.

Historical API

We are working on an additional end point specifically to send your historical data. Is that important for you?
Tell us more by voting on what matters to you in our product roadmap.

Did you find this article helpful ?