How to Integrate your generated data in external applications
You want to integrate data in any other platform or billboards we offer two options for retrieving data
Get any generated event directly from the box without processing it through the cloud use the MQTT option
Be aware that in this option you get the data of each event, and you can't use Data Analytics in our SWARM Perception Platform
Access Data Analytics widgets underlying data via API
For every Data Analytics widget, the underlying data can be queried via a provided REST API. Integration to third-party applications works out fast and easy.
The REST API makes generated event data available to third-party applications, retrieved from your Data Analytics widgets.
Once you configure a widget, find the item "API call" in the side menu.
The provided dialog pop up shows detailed information on how the API request for the generated data of this particular widget looks like. Copy/paste the curl command into a terminal and execute it. You can directly test the call within the dialog, including the response format, by clicking on "Try it out!" which does not require the usage of a terminal.
The provided access token is temporary. For a permanent integration into third-party applications, please request a permanent access token via the Support Portal.
We strictly follow the OAuth flow documented by Microsoft. There are several client libraries that you can use.
In the GitHub repository below you can find example code that highlights how to integrate the data into your own application. It showcases how to handle the required authentication as well as how to perform queries.
You can see a Data Analytics widget for bicycle counting as an example below. The respective type of widget (Traffic Counting) is selected, data is aggregated per day, split by object class and direction, and we filter for bicycles only.
API Request
The API-Call option shows the respective GET request for this data, as you can see below.
API Response (shortened)
The REST API is based on Cube.js. More information on the functionality of the API can be found in the external documentation.
API to gather the specific data out of the Swarm Control Center
Every setting and information available in the Control Center can be gathered via an API. The Swagger documentation for our demo instance as an example can be found here: Swagger UI
Generally we stick to the following OAUTH flow documented here OAuth 2.0 client credentials flow on the Microsoft identity platform - Microsoft Entra
Make sure to add your tenant ID as a header in the authentication flow.
To gather the first part of the URL for your specific API Documentation/Swagger UI you can either contact our support or grab it from the source code of your Control Center.
Go to the Swagger UI
2. The API call above will give you the status of a device and returns the following:
3. The states are defined in the API documentation below
4. You can as well get the state of the individual streams. The API returns the following:
Getting started with your custom MQTT connection
As soon as you have configured your use case in the Swarm Control Center, the SWARM software generates events. These events are transferred as standard JSON.
In case you don't want to use Data Analytics and retrieve data via SWARM API, we provide you the option to configure a custom MQTT broker.
The Swarm Perception Box will send events in the form of a JSON to an MQTT broker you configure. The QoS level 1 is used to deliver events. In case events cannot be delivered, e.g. no connectivity, we cache events up to 24k messages. The stream UUID is set automatically as MQTT client id.
For higher security, you can use MQTT over SSL. Simply add ssl:// prefix to the broker configuration.
In case that message compression is configured, the events are compressed with zlib / inflate .
There are several ways how to validate a JSON against a schema, a good overview is provided by json-schema.org. As a starting point, we recommend jsonschemalint.com, an online tool to manually validate a JSON against our schema.
The header of the JSON is defined by a version of the format being used (property version
). The format is major.minor
, a major version change denotes a breaking change whereas a minor version change indicates backward compatibility. For unique identifiers, we rely on UUID. Timestamps are defined with ISO8601.
A counting line event is triggered if an object crosses a virtual line (identified by the property lineId
). The line has a user-defined name (property lineName
). A timestamp (property timestamp
) is set when the event occurred. The object can cross the line in two directions (property direction
) and is either moving in or out. Additionally, the object that crosses the line is classified (property class
& sublcass
). The classes are dependent on the use case.
In case the ANPR feature is enabled, the license plate (property plateNumber
) and the license plate country (property numberPlateOrigin
) will be added to the event.
With ANPR there are captures of the license plate at entries and exits taken. The License plate capture can be attached in JPG format to the MQTT message encoded with BASE64.
Please contact our support to enable the addition of license plate captures via MQTT.
If speed estimation is enabled and configured, the speed estimate (property speedestimate
) will give the speed estimate output in km/h.
The Region of Interest Event depends on the type of the Region of Interest. Region of Interest with RoI-type Parking will generate a ParkingEvent
and the RoI type Generic will generate a RegionOfInterestEvent
A parking event is triggered by a time interval every 10 seconds. The information of all the configured Parking RoI will be aggregated in one single event. In parkingSummary
all the RoI will be listed with the configured capacity
and the current count of vehicles
in the RoI.
As a total summary, you will have the totalCapacity
and the totalVehicles
which gives a complete overview of all configured Parking RoI in this camera stream.
As an Early Availability feature, you can enable ANPR for Parking RoI. This will provide the license plate (property plateNumber
) and the license plate country (property numberPlateOrigin
) in a string format.
A region of interest event is triggered either by a state change or by a time interval (property triggerType
). The state (property state
) can change from occupied to vacant or vice-versa. It is occupied in case the number of objects in the RoI is at least as high as the configured capacity
.
Every event contains a user-defined name (property roiName
) and a timestamp (property timestamp
) when the event occurred. Detected objects and their associated class and dwell times are listed (property objects
). The classes are dependent on the use case.
In case a rule is created on an event trigger, a rule event is sent. The rule event is triggered based on the chosen event trigger logic in combination with the defined conditions. A timestamp (property timestamp
) is set when the event occurred. The rule event includes the generic information around the rule name, device and stream UUID. On top of the event information, the chosen standard event information is part of the message in the same format as for the standard messages of the chosen event triggers.
Raw track mode traces objects as they move through the field of view. A complete trace, of the route that the object took, is generated as soon as the object exits the field of view.
This trace includes the classification of the object (property class
) and the path of the object throughout the field of view. The class is dependent on the particular use case.
The track is described as a series of path
elements, which include a timestamp and the top-left coordinates along with width and height of the tracked object. There are a maximum of 10 path elements in every event.
Breakdown of Object related attributes:
Every event does contain a class of the detected object. We arranged those objects in classes and subclasses for a better overview. You can see the classes and Subclasses as well as examples in the section models.
Example Counting Line detecting a Van. Note that the class is "car" and the subclass is "van".