Skip to main content

API

This tutorial is for software integrators who use the API interface of uBeacon Tools software as background business functions. Through the API interface, you can obtain the UID, coordinates, power, working status of Gateway, uBeacon, Tag devices, and real-time positioning of the Tag. The data format is JSON, and the interface protocols include MQTT, UDP, webhook, HTTP, etc. The software supports deployment on Ubuntu, Windows, MacOs and other platforms.

1. Data Format: JSON

Location Data Example

{
"data": {
"pos": [
-3.2616942,
4.3123593,
1.1999172
], // Positioning: x,y,z
"posNoise": [
0.71,
0.62,
0.03
],// Positioning noise: x, y, z, the larger the value, the lower the confidence
"time": 575889100, // Position timestamp
"vel": [
-0.08,
0.1,
0
], //速度:x,y,z
"velNoise": [
0.13,
0.13,
0.01
] //Velocity noise in the x, y, and z directions. The larger the value, the lower the confidence
},
"deviceName": "T4", // Device name, unique within the software
"name": "Pos", // Message Type
"uid": "02084a71676424f9e16d" //Device UID
}

2. Tag Location Data API Configuration Entry

Open the uBeacon Tool software and follow the steps below to enter the configuration page.

API configuration entry example

3. MQTT Obtains Tag Location Data

api.mqtt.address: {IP or Domain name}:{Interface}

api.mqtt.clientId: Client ID, can be empty

api.mqtt.topic: Theme Name

MQTT configuration example

4. UDP Obtains Tag Positioning Data

api.udp.address: {IP or Domain name}:{Interface}

UDP configuration example

5. Webhook Obtains Tag Location Data

api.hook.url format: http://{IP or Domain name}:{Interface}/{Custom uri}

http method: POST

Web hook configuration example

6. HTTP to Get Device Status

URL: GET http://localhost:8088/openapi/v1/devices?deviceType=&online=&query=&page=&pageSize=

Query parameters:

Parameter nameParameter TypeParameter Description
deviceTypeintSearch by device type. Empty means querying all types of devices. 1 means querying Gateway devices. 2 means querying uBeacon devices. 3 means querying Tag devices.
onlineboolAccording to whether to search online, empty means to query all states, false means to query offline devices, true means to query online devices
querystringSearch by device name prefix or device UID suffix
pageintThe default pagination number is 1, which means the first page, and so on.
pageSizeintThe default page size is 20, and the maximum is 100.

Response data:

{
"code": 0, // 0 indicates success, non-0 indicates failure
"message": "",
"data": {
"records": [
{
"name": "U6", // Device Name
"type": 2, // Device type, 1 indicates Gateway device, 2 indicates uBeacon device, 3 indicates Tag device
"online": false, // Is online
"onlineTime": 1727323909, //Online and offline time. "online" is true for online time, and "online" is false for offline time.
"uid": "0208f5579f8e183fa1eb", // Device UID
"power": 93, // Device battery percentage
"coordinate": { // Device coordinates, currently only available for uBeacon devices
"coords": [
13.302, // x-coordinate
12.9, // y-coordinate
2.9 // z-coordinate
]
}
}
],
"total": 1 // The total number of current search terms
}
}