OptiCloud API – How to use it step by step

All the data you send to Opticloud, whether simple uptime, downtime, part counters, or more advanced data from your ERP or SCADA, such as order information, vibration, temperature, etc. We have an API for it.

All APIs are REST and use JSON as the format. We have one streamlined way of getting data, where you can simply change parameters in the URL to get what you need when you need it.

We use a method where some APIs are GET where you’ll be able to get the data you need, and some APIs are POST where you’ll be able to post data to us from your other platforms. It could be order data from your Dynamics 365 for example.

For some data like machine data, you’ll need to send it through MQTT instead. We have another guide for that, please reach out to hi@optipeople.dk if you are interested.

But for getting data, all APIs use REST and are available through regular HTTPS port 443. So just a standard internet connection is needed. You can even test the API in your browser. We’ll get to that.

How to GET data and test connection

For getting data from Opticloud, you’ll need the following steps completed:

1. Having an account set up and ready at the portal.optipeople.dk, if you haven’t already then reach out to hi@optipeople.dk or +45 23 74 47 05 to get started.
2. Added a machine and a device on the portal.
3. Sending data to the device.
4. Get your access key. Go to portal.optipeople.dk > Account > information > API > Create API.

If you need help with any of the above, please reach out.

I’ve created an account for testing purposes, which has machine data. Feel free to use it as well.

Account name: Opti Virtual Demo
Factory name: Optipeople Demo Factory
Machines: Opti001, Opti002
Shift enabled: Morning, Day, Evening, Night
API access key: B1C3ECDD80faF72C498F1FFDe7741099085b4F5f7D33f60e1375Efd659bC7f2f

Testing the connection

To test the connection, simply use this URL:

https://dataexport.optipeople.dk/api/DataExport/GetDataExport?access_code=B1C3ECDD80faF72C498F1FFDe7741099085b4F5f7D33f60e1375Efd659bC7f2f

This will give you a result from our DataExport API. You can see what API you are using by looking at what comes after dataexport.optipeople.dk/api/DataExport/.

If you click on the link, you’ll most likely see something looking like this:

This is normal. It’s JSON with all the data, so it means you have a connection and everything is good. If you want to be able to read it more clearly, you can install a JSON viewer for your browser. Any JSON viewer will do.

Adding extensions/parameters

There are several extensions to the URL that you can use. The URL above only gives you data from all machines at the selected customer for the current day. But you can also choose individual machines by using &machineId=”GUID” at the end of the URL. You can find the machine id for any machine in the portal, by looking at the URL either in the settings of a machine or in the operator panel. Alternatively, you can also find the machine id in the API export as well. Look under “shiftdata”, on each shift you have a machine id and corresponding machine name.

You can also use &from=datetime and &to=datetime. For example, if you wanted to get data from the 1st January 2022 to the 1st February 2022, you’d write &from=01-01-2022&to=01-02-2022.

The different APIs available

We have many APIs that are available for our customers, right from the start. Down below are the most commonly used.

GetEventExport

GetEventExport will give you a raw output of the events we receive from the machine. So it’s runtime and downtime messages.

You have two arrays or subschemas “machineId” and “events”. The machineId is the one referring to what machine the event happened on. We’ve made the API lightweight so there is no additional information added, such as machine name. You can use the GetDataExport to see which machine the id belongs to.

In the “events” array, you can see 7 instances. Most of them are self-explanatory, like start and end time stamps. All events have shiftName and shiftId attached, so you can relate them to the shiftdata array in GetDataExport. This way you can group/sort events that happened in specific shifts.

URL example for GetEventExport:

https://dataexport.optipeople.dk/api/DataExport/GetEventExport?access_code=B1C3ECDD80faF72C498F1FFDe7741099085b4F5f7D33f60e1375Efd659bC7f2f

GetDataExport

The GetDataExport API is our most used API. Here you’ll find all data related to efficiency like availability, performance, quality, units, shifts, stop causes, and more. This API is specially used in BI tools like Microsoft Power BI.

The GetDataExport API is much larger and is intended for reporting purposes.

The API consists of 6 arrays/subschemas or tables if you convert it to an SQL DB i.e.

shiftData

The shiftdata table shows all shifts in the chosen period. Besides identifiers like machines and factories, you also have a calculated number on how much planned and unplanned downtime or stop time the machine has had throughout the shift. This is a calculation taken from the wasteData table. You’ll also see how many units have been produced and how has been rejected.

So basically from the shiftData table alone, you can calculate your Availability, Performance, and Quality.

Example of getting the number of seconds of availability:

Take durationInSec minus unplannedWasteDurationInSec and you have the number of seconds of availability you’ve had. To get the actual effective time:

Take durationInSec minus plannedWasteDurationInSec and minus the unplannedWasteDurationInSec.

URL example for GetDataExport:

https://dataexport.optipeople.dk/api/DataExport/GetDataExport?access_code=B1C3ECDD80faF72C498F1FFDe7741099085b4F5f7D33f60e1375Efd659bC7f2f

counterData

The counterData table holds all the actual unit counters you have on your machine. You can have as many counters or tags as you want per machine. Many of our customers use several different counters like meters, square meters (m2), kilos, press, etc. But it could also be just a simple unit counter to show how many goods are produced in a single order.

unitData

Where the counterData stores the actual counted units for each counter or tag, the unitData table stores what order or item is currently being produced. This is typically an automated or semi-automated process where unit data is sent from the customers’ PLC or ERP system.

It’s also in the unitData table we get our baseline for the production speed or performance calculation. The speedUnitsHour is how many units you expected the machine can produce in an hour on that order/item number. This number can either be sent directly with the unitName/Id from your ERP or be manual input from operators.

wasteData

The wasteData table is barebone for all stops related to the machine. Stops or wastes as we call them, can both be automated stop registrations from the machine and/or PLC or simple manual registrations from the operators at the machine.

Wastes can be a child or a parent to another waste. You can create a folder/directory-like structure for your wastes if you have many. If it says “Root” like in the image above, it’s because it has no parents attached to it.

Wastes can also hold comments because operators can leave comments on wastes to add additional information to them.

Wastes can be planned or unplanned. If it’s a planned stop, it’ll go into the plannedDurationInSec in the shiftData table and if it’s unplanned it’ll go into the unplannedDurationInSec.

GetTPMAlertsExport

The TPMAlersExport API is a bit different than any of the others. This API is not directly related to any efficiency modules but is its own module/feature altogether. In the portal, you can create alarms based on time intervals, production hours, and counters. These alarms will be shown to operators and sent via email, but also be available in the API for report and viewing purposes.

In the API you have all the basic stuff like the name, information, timestamp, alarm type, machined, eventId, etc. Two things that are of importance are the “tpmSigned” and “tpmSignedTimeOfOccurence”.

These two indicate whether an alarm has been signed off or not. So whether the task is done or not or whether the problem is still an issue or not.

SetMachinePartInformation

SetMachinePartInformation is one of our most used POST-APIs. Via this API you can POST unit information like order numbers and item numbers with expected speeds. We use this to calculate the correct performance in real-time. I won’t go into detail about the API here. If you want to see an example and get the information, please reach out to hi@optipeople.dk or call us at +45 23 74 47 05.