You can check if you have API license using ObX Admin Tools, from the Main page, click on the Check License Info
This will open a License Viewer dialog in which you can see all list of features license to you ObX Historian Server. Make sure the API license is checked, it means you have API license.
Create an API User
Open ObX Admin Tools and from the left pane Go to -> Users -> API
Right-click on the API -> Add User , this will open a new window for creating a User in the ObX historian.
Fill in all the fields:
Username (required) - the username used by the 3rd party software to connect.
Password (required) - the password used by the 3rd party software to connect.
Confirm (required) - for password confirmation.
Description (optional)
Grant - Check this where you want to give this API user an access to specific datasource.
Privilege - Select what type of privilege this API user will have to specific datasource, for example READ - for read only, WRITE - for write only, ALL - for both read and write.
Click on CREATE button to finish.
API Configuration
The API uses basic authentication, which uses a username and password created in the ObX Admin Tools.
API Endpoint
https://{IP Address}/db/live
IP Address - the IP address where the ObX WebUI component is installed.
Query Paremeters
q : The query (SQL like) to fetch data in the ObX Historian.
SELECT mean("value") FROM "Tag1" WHERE time >=now()-5m GROUP BY time(1m) tz('Asia/Singapore');
// This query return the average/mean value of Tag1 for the last 5minutes sampled every 1 minute of data.
// The tz is your current timezone, this is necessary to avoid time region confusion.
SELECT "value" FROM "Tag1" WHERE time >=now()-1m ORDER BY time DESC LIMIT 1;
// This query return the last or current value of the Tag.
SELECT "value" FROM "Tag1" WHERE time >=now()-1m
/* This query returns all the values - raw value without sampling for the last 1 minute of data*/
SELECT mean("value") FROM "Tag1" WHERE time >=1726651500000ms and time <=1726652100000ms GROUP BY time(1m) tz('Asia/Singapore)
/*This query return average/mean value of Tag1 between 2024-09-18 17:25:00 and 2024-09-18 17:35:00
Notice that the time accepted by the API is a milliseconds Unix epoch timestamp, so
you need to convert your time in ms. */
/*Using nodeJS or Javascript you can simply */
startTime = new Date('2024-09-18 17:25:00).getTime() // to get the Unix epoch timestamp
db: The datasource name in the ObX Historian.
Example Using Postman
URL:
https://localhost/db/live
Query Parameters:
Query Parameters
Value
q
SELECT mean("value") FROM "Counter" WHERE time >=now()-1h GROUP BY time(1m)
db
Energy
Authentication:
Note that in Authentication, you have to use the Basic Auth and use the credentials created in the ObX Admin Tools.
You can also simply use a web browser and type in directly into URL
https://localhost/db/live?q=SELECT mean("value") FROM "Counter" WHERE time >=now()-1h GROUP BY time(1m)&db=Energy
If you are using a NodeJS or any framework to connect to the API, make sure the disable the tls verification, the API uses a self-signed-certificates, by default all frameworks verifies this and interrupts all connection with a self-signed-certificates.
Example Using NodeJS
Using axios library (but you can use any libraries)
const axios = require('axios');
const https = require('https');
// Disable TLS verification
const agent = new https.Agent({
rejectUnauthorized: false,
});
// Send the GET request
axios.get('https://localhost/db/live', {
params: {
q: 'select "value" from "Counter" Where time >=now()-1m',
db: 'Energy',
},
headers: {
'Content-Type': 'application/json',
'Authorization': 'Basic ' + Buffer.from('your-username:your-password').toString('base64'), // Replace with your credentials
},
httpsAgent: agent, // Set the custom HTTPS agent
})
.then(response => {
console.log(response.data);
})
.catch(error => {
console.error('Error:', error);
});
