API
This tutorial is intended for software integrators who perform backend business functions based on the API interface of uBeacon Tools software. Through the API interface, you can obtain the UID, coordinates, power, working status of the Gateway, uBeacon, and Tag devices, as well as the 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
], //position：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, //Positioning timestamp.
"vel": [
-0.08,
0.1,
0
], //Velocity：x,y,z
"velNoise": [
0.13,
0.13,
0.01
], //Velocity noise：x,y,z, the larger the value, the lower the confidence.
"fences": [
{
"id": 18, //The ID of the electronic fence where the tag is located
"name": "Fence-13", // The name of the electronic fence where the tag is located
"userData": {} // User-defined data
}
],
"optPoses": [
[
0.71,
0.62,
0.03
]
] // The position after adding boundary or wall constraints
},
"deviceName": "T4", //Device name, which is unique within the software.
"name": "Pos", // Message type
"uid": "02084a71676424f9e16d" //Device UID
}
2. Push data API configuration entrance
Open the uBeacon Tool software and follow the steps below to enter the configuration page.
3. Push data through MQTT protocol
address: Protocol://username:password@hostname:port or Protocol://hostname:port or hostname:port
Unencrypted Protocol support: mqtt or tcp, ws
Encryption Protocol support: mqtts or tcps, wss
Example：mqtt://admin:test@192.168.0.15:1883
clientId: Client identification, can be empty
topic: Topic name
4. Push data through UDP protocol
address: {ip or domain name}:{port}
localAddress: Specify the local IP address, mainly to specify the selected network card when there are multiple network cards
5. Push data through webhook protocol
api.hook.url格式: http://{ip or domain name}:{port}/{custom uri}
http method: POST
6. Get device status through HTTP protocol
URL: GET http://localhost:8088/openapi/v1/devices?deviceType=&online=&query=&page=&pageSize=
Query parameter:
| Parameter name | Parameter type | Parameter description |
|---|---|---|
| deviceType | int | Search based on device type. Empty means querying all types of devices, 1 means querying Gateway devices, 2 means querying uBeacon devices, and 3 means querying Tag devices. |
| online | bool | Depending on whether to search online, empty means querying all statuses, false means querying offline devices, and true means querying online devices. |
| query | string | Search based on device name prefix or device UID suffix |
| page | int | Pagination page number, the default is 1, 1 means the first page, and so on. |
| pageSize | int | The size of each page for paging, the default is 20, 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 represents Gateway device, 2 represents uBeacon device, 3 represents Tag device
"online": false, // Device online status
"onlineTime": 1727323909, // Online and offline time, online is true to indicate online time, online is false to indicate offline time
"uid": "0208f5579f8e183fa1eb", // Device UID
"power": 93, // Device battery percentage
"coordinate": { // Device coordinates, currently only uBeacon devices have
"coords": [
13.302, // x-axis
12.9, // y-axis
2.9 // z-axis
]
}
}
],
"total": 1 // Total number for current search criteria
}
}
7. Query electronic fences on the map through HTTP protocol
URL: GET http://localhost:8088/openapi/v1/maps/{mapId}/fences
Path Parameter:
| Parameter name | Parameter type | Parameter description |
|---|---|---|
| mapId | uint32 | Geo-fence location map ID |
Response data:
{
"code": 0, // 0 indicates success, non-0 indicates failure
"message": "",
"data": {
"records": [
{
"id": 11, // Electronic fence id
"mapId": 2, // Geo-fence location map ID
"name": "Test", // Electronic fence name
"enable": true, // Is the electronic fence enabled
"bounds": [
[
[
19.305483719334006,
14.511200794018805
],
[
21.019341055303812,
14.511200794018805
],
[
21.019341055303812,
13.554935615509748
],
[
19.305483719334006,
13.554935615509748
],
[
19.305483719334006,
14.511200794018805
]
]
], // Geo-fence boundaries (holes are not currently supported)
"leaveBuffer": 0.3, // When the distance from the electronic fence boundary is greater than leaveBuffer, it is considered to have left.
"includes": ["d910570506e6d4f7"],// The tag UID of the electronic fence that is effective. If it is empty, it means all are effective.
"excludes": ["d48475ae51904290"],//The tag UID for which the electronic fence is not effective. If it is empty, it means all are effective.
"userData": {} // User-defined data
}
]
}
}
8. Search electronic fences through HTTP protocol
URL: GET http://localhost:8088/openapi/v1/fences
Query Parameter:
| Parameter name | Parameter type | Parameter description |
|---|---|---|
| mapId | uint32 | Geo-fence location map ID |
| query | string | Search by geo-fence name prefix |
| page | int | The default pagination number is 1, which means the first page, and so on. |
| pageSize | int | The default page size is 20, and the maximum is 100. |
Response data:
{
"code": 0, // 0 indicates success, non-0 indicates failure
"message": "",
"data": {
"records": [
{
"id": 11, // Electronic fence id
"mapId": 2, // Geo-fence location map ID
"name": "Test", // Electronic fence name
"enable": true, // Is the electronic fence enabled
"bounds": [
[
[
19.305483719334006,
14.511200794018805
],
[
21.019341055303812,
14.511200794018805
],
[
21.019341055303812,
13.554935615509748
],
[
19.305483719334006,
13.554935615509748
],
[
19.305483719334006,
14.511200794018805
]
]
], // Geo-fence boundaries (holes are not currently supported)
"leaveBuffer": 0.3, // When the distance from the electronic fence boundary is greater than leaveBuffer, it is considered to have left.
"includes": ["d910570506e6d4f7"],// The tag UID of the electronic fence that is effective. If it is empty, it means all are effective.
"excludes": ["d48475ae51904290"],//The tag UID for which the electronic fence is not effective. If it is empty, it means all are effective.
"userData": {} // User-defined data
}
],
"total": 1 // The total number of current search terms
}
}
9. Load some electronic fence through HTTP protocol
URL: GET http://localhost:8088/openapi/v1/fences/\{id\}
Path Parameter:
| Parameter name | Parameter type | Parameter description |
|---|---|---|
| id | uint32 | Electronic fence id |
Response data:
{
"code": 0, // 0 indicates success, non-0 indicates failure
"message": "",
"data": {
"mapId": 2, // Geo-fence location map ID
"name": "Test", // Electronic fence name
"enable": true, // Is the electronic fence enabled
"bounds": [
[
[
19.305483719334006,
14.511200794018805
],
[
21.019341055303812,
14.511200794018805
],
[
21.019341055303812,
13.554935615509748
],
[
19.305483719334006,
13.554935615509748
],
[
19.305483719334006,
14.511200794018805
]
]
], // Geo-fence boundaries (holes are not currently supported)
"leaveBuffer": 0.3, // When the distance from the electronic fence boundary is greater than leaveBuffer, it is considered to have left.
"includes": ["d910570506e6d4f7"],// The tag UID of the electronic fence that is effective. If it is empty, it means all are effective.
"excludes": ["d48475ae51904290"],//The tag UID for which the electronic fence is not effective. If it is empty, it means all are effective.
"userData": {} // User-defined data
}
}
10. Add electronic fence through HTTP protocol
URL: POST http://localhost:8088/openapi/v1/fences
Response data:
| Parameter name | Parameter type | Parameter description |
|---|---|---|
| name | string | Electronic fence name |
| enable | bool | Is the electronic fence enabled |
| bounds | [][][][][][][]float64 | Geo-fence boundaries (holes are not currently supported) |
| leaveBuffer | float64 | When the distance from the electronic fence boundary is greater than leaveBuffer, it is considered to have left. |
| includes | []string | The tag UID of the electronic fence that is effective. If it is empty, it means all are effective. |
| excludes | []string | The tag UID for which the electronic fence is not effective. If it is empty, it means all are effective. |
| userData | Object | User-defined data |
{
"mapId": 2, // Geo-fence location map ID
"name": "Test", // Electronic fence name
"enable": true, // Is the electronic fence enabled
"bounds": [
[
[
19.305483719334006,
14.511200794018805
],
[
21.019341055303812,
14.511200794018805
],
[
21.019341055303812,
13.554935615509748
],
[
19.305483719334006,
13.554935615509748
],
[
19.305483719334006,
14.511200794018805
]
]
], // Geo-fence boundaries (holes are not currently supported)
"leaveBuffer": 0.3, // When the distance from the electronic fence boundary is greater than leaveBuffer, it is considered to have left.
"includes": ["d910570506e6d4f7"],// The tag UID of the electronic fence that is effective. If it is empty, it means all are effective.
"excludes": ["d48475ae51904290"],//The tag UID for which the electronic fence is not effective. If it is empty, it means all are effective.
"userData": {} // User-defined data
}
Response data:
{
"code": 0, // 0 indicates success, non-0 indicates failure
"message": ""
}
11. Update electronic fence through HTTP protocol
URL: PUT http://localhost:8088/openapi/v1/fences/{id}
Response data:
| Parameter name | Parameter type | Parameter description |
|---|---|---|
| id | uint32 | Electronic fence id |
Body参数：
| Parameter name | Parameter type | Parameter description |
|---|---|---|
| name | string | Electronic fence name |
| enable | bool | Is the electronic fence enabled |
| bounds | [][][][][][][]float64 | Geo-fence boundaries (holes are not currently supported) |
| leaveBuffer | float64 | When the distance from the electronic fence boundary is greater than leaveBuffer, it is considered to have left. |
| includes | []string | The tag UID of the electronic fence that is effective. If it is empty, it means all are effective. |
| excludes | []string | The tag UID for which the electronic fence is not effective. If it is empty, it means all are effective. |
| userData | Object | User-defined data |
{
"name": "Test", // Electronic fence name
"enable": true, // Is the electronic fence enabled
"bounds": [
[
[
19.305483719334006,
14.511200794018805
],
[
21.019341055303812,
14.511200794018805
],
[
21.019341055303812,
13.554935615509748
],
[
19.305483719334006,
13.554935615509748
],
[
19.305483719334006,
14.511200794018805
]
]
], // Geo-fence boundaries (holes are not currently supported)
"leaveBuffer": 0.3, // When the distance from the electronic fence boundary is greater than leaveBuffer, it is considered to have left.
"includes": ["d910570506e6d4f7"],// The tag UID of the electronic fence that is effective. If it is empty, it means all are effective.
"excludes": ["d48475ae51904290"],//The tag UID for which the electronic fence is not effective. If it is empty, it means all are effective.
"userData": {} // User-defined data
}
Response data:
{
"code": 0, // 0 indicates success, non-0 indicates failure
"message": ""
}
12. Delete electronic fence through HTTP protocol
URL: DELETE http://localhost:8088/openapi/v1/fences/{id}
Path Parameter:
| Parameter name | Parameter type | Parameter description |
|---|---|---|
| id | uint32 | Electronic fence id |
Response data:
{
"code": 0, // 0 indicates success, non-0 indicates failure
"message": ""
}