Localization Data

To send localization data to the Twinzo REST API, you'll need to configure the sectors and import your layouts to the digital twin. Please refer to the twinzo coordination system docs for more information on this process.

Note that localization only works for registered devices.

API Endpoint

To send localization data, you can either send data for each device individually or send a batch of data for multiple devices at once.
When sending data, you must include information about the position, timestamp, sector, and device identifier (for batch scenarios).
The only difference in data payload is, that batch localization is wrapping the location contract into the parent object with the device login identifier.

/localization/

Used when the device sends data on its own.
The device uses a login/password to obtain an OAuth token, which is then signed.

/localization/batch

Used when the API, middleware, or edge computer sends data for multiple devices.
An array of device localization data is sent, each identified using Login.
A static API key is used for signing.

Twinzo handles both use cases same and unifies features for both methods. Use the method accordingly to your needs and requirements. Every single sensor can group multiple different quantities.

Example

The data contracts available for third-party integration are described below. Note that other fields visible in the Swagger, but not mentioned in the public documentation are only used for twinzo's RTLS BLE solution and can be ignored. Coordinates must comply with the settings of the sector coordinate system described in the sector edit section of the documentation.

Device data send is when each device sends its own data independently, without waiting for other devices.
Batch data send is when multiple devices synchronize their data and send it together, either through an API or an edge device.

Device data

[
  {
    "Timestamp": 0,
    "SectorId": 0,
    "X": 0,
    "Y": 0,
    "Z": 0,
    "Interval": 0,
    "Battery": 0,
    "IsMoving": true,
    "LocalizationAreas": [
      0
    ],
    "NoGoAreas": [
      0
    ]
  }
]

Batch data

[
  {
    "Login": "string",
    "Locations": [
      {
        "Timestamp": 0,
        "SectorId": 0,
        "X": 0,
        "Y": 0,
        "Z": 0,
        "Interval": 0,
        "Battery": 0,
        "IsMoving": true,
        "LocalizationAreas": [
          0
        ],
        "NoGoAreas": [
          0
        ]
      }
    ]
  }
]

Data Properties

Here's a table listing the JSON parameters and their descriptions:

Login	Sensor login field used as a unique identifier in the batch data POST.
Timestamp	A Unix timestamp in milliseconds that represents the time when the data was collected.
SectorId	An integer that represents the sector ID where the location data was collected.
X	A number that represents the X coordinate of the location data in millimeter (mm).
Y	A number that represents the Y coordinate of the location data in millimeter (mm).
Z	A number that represents the Z coordinate of the location data in millimeter (mm).
Interval	An integer that represents the interval at which the location data was collected. This interval refers to the expected time gap between localization records. If the time gap between records is more than 10 times the interval, the next position will be marked as "respawn."
Battery	An integer that represents the battery level at which the location data was collected.
IsMoving	A boolean value that indicates whether or not the device was moving when the location data was collected. If the source system does not possess this information, a true value is required by default. Otherwise, devices won't move correctly in the 3D application.
LocalizationAreas	A list of IDs of the areas in which the device is currently present.
NoGoAreas	A list of IDs of the no-go areas in which the device is currently present.

Axis directions

There is an image with the axis directions below. We are using IV. quadrant (green).