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:

Variable Metric value in the API Asset to associate
flow flow pipe
pressure pressure junction
pump status status pump
valve status status valve
valve setting setting valve
tank level level tank
demand demand junction

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>
...

 

Variables Legend Format Example
time The time when the reading was taken. string

(timestamp in ISO 8601 format)

“2021-11-03T15:00:00Z”
asset The 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”
value The 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
metric The 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.

Code Description
200 No error
400 Bad request
401 Authentication token missing or invalid
403 Forbidden
404 Not found
413 The message body is too large
429 Too many requests. When over the rate limits
500 Unexpected 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 ?