API

This tutorial is intended for software integrators who perform backend business functions based on the API interface of IPS Tools software. Through the API interface, you can obtain the UID, coordinates, power, working status of the Anchor, 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": {
        "mapId": 2, // The floor where the location is located.
        "pos": [
            -3.2616942,
            4.3123593,
            1.1999172
        ], //Position：x,y,z
        "noiseRadius": 0.085815825, //Positioning noise, the larger the value, the lower the confidence.
        "posVar": [
            0.71,
            0.62,
            0.03
        ], //Positioning noise：x,y,z
        "time": 1731034496, //Positioning unix timestamp.
        "vel": [
            -0.08,
            0.1,
            0
        ], //Velocity：x,y,z
        "velVar": [
            0.13,
            0.13,
            0.01
        ], //Velocity noise：x,y,z
        "properties": {
        	"tansmit": "xxxxxxxxxxxx"  // Transparent transmission data, encoded by base64.
    	},
        "rxAnchorSn": "1e00400007503148", // The Anchor device UID corresponding to the strongest signal strength received.
        "rxRssi": -47.235565185546875, // The strongest signal strength received
        "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": "ea221ffdb4fbea42",  //Device UID
    
}

Tag call data example：

{
    "deviceName": "T4", //Device name, which is unique within the software.
    "name": "Call", // Message type
    "uid": "ea221ffdb4fbea42"  //Device UID
}

Tag Cancel Call Data Example：

{
    "deviceName": "T4", //Device name, which is unique within the software.
    "name": "CancelCall", // Message type
    "uid": "ea221ffdb4fbea42"  //Device UID
}

Tag response user call data example：

{
    "deviceName": "T4", //Device name, which is unique within the software.
    "name": "Ack", // Message type
    "uid": "ea221ffdb4fbea42",  //Device UID
    "data": { 
    	"reqId": "CallAck"  // Request ID of the response
	}
}

Tag response user cancel call data example：

{
    "deviceName": "T4", //Device name, which is unique within the software.
    "name": "Ack", // Message type
    "uid": "ea221ffdb4fbea42",  //Device UID
    "data": {
    	"reqId": "CancelCallAck" // Request ID of the response
	}
}

2. Push data API configuration entry

Open the IPS 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

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

url格式: http://{ip or domain name}:{port}/{custom uri}

http method: POST

6. Get device status through HTTP protocol

URL: GET http://localhost:8080/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, 4 means querying Anchor devices, 5 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 prefix
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": [
          {
            "type": 4,  // Device type, 4 represents Anchor device, 5 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": "1b00530007503148", // Device UID
            "product": "A01", // Device product
            "coordinate": { // Device coordinates, currently only Anchor devices have
                "coords": [
                  13.302,  // x-axis
                  12.9,    // y-axis
                  2.9      // z-axis
                ]
             },
             "name": "A1" // Device name
           },
           {
             "type": 5, // Device type, 4 represents Anchor device, 5 represents Tag device
             "online": false, // Device online status
             "onlineTime": 1730860539, // Online and offline time, online is true to indicate online time, online is false to indicate offline time
             "uid": "72bc78a7911d836f", // Device UID
             "power": 50,  // Device battery percentage
             "product": "T02", // Device product
             "name": "T5" // Device name
           }
    	],
    	"total": 1 // Total number for current search criteria
    }
}

7. Send transparent data to tag through HTTP protocol

URL: PUT http://localhost:8080/openapi/v1/devices/{uid}/services/TransmitData

Query Parameter:

Parameter name	Parameter type	Parameter description
uid	string	Device UID

Body Parameter:

Parameter name	Parameter type	Parameter description
data.data	string	Transparent data.
data.codec	string	Data encoding format, utf8 means utf8 encoding, hex means hex encoding, empty or other means base64 encoding

{
    "data":{
        "data":"123",
        "codec":"utf8"
    }
}

Response data:

{
    "code": 0, // 0 indicates success, non-0 indicates failure
    "message": ""
}

8. Send formatted transparent data to tag through HTTP protocol

URL: PUT http://localhost:8080/openapi/v1/devices/{uid}/services/FormatTransmitData

Query Parameter:

Parameter name	Parameter type	Parameter description
uid	string	Device UID

Body Parameter:

Parameter name	Parameter type	Parameter description
data.data	string	Transparent data.
data.codec	string	Data encoding format, utf8 means utf8 encoding, hex means hex encoding, empty or other means base64 encoding

{
    "data":{
        "data":"123",
        "codec":"utf8"
    }
}

Response data:

{
    "code": 0, // 0 indicates success, non-0 indicates failure
    "message": ""
}

9. Send call command to tag through HTTP protocol

URL: PUT http://localhost:8080/openapi/v1/devices/{uid}/services/Call

Query Parameter:

Parameter name	Parameter type	Parameter description
uid	string	Device UID

Body Parameter:

Parameter name	Parameter type	Parameter description
data.duration	int	Call duration, unit: s, maximum: 64

{
    "data":{
        "duration": 1
    }
}

Response data:

{
    "code": 0, // 0 indicates success, non-0 indicates failure
    "message": ""
}

10. Send a cancel call command to tag through HTTP protocol

URL: PUT http://localhost:8080/openapi/v1/devices/{uid}/services/CancelCall

Query Parameter:

Parameter name	Parameter type	Parameter description
uid	string	Device UID

Response data:

{
    "code": 0, // 0 indicates success, non-0 indicates failure
    "message": ""
}

11. Send response call command to tag through HTTP protocol

URL: PUT http://localhost:8080/openapi/v1/devices/{uid}/services/Ack

Query Parameter:

Parameter name	Parameter type	Parameter description
uid	string	Device UID

Body Parameter:

Parameter name	Parameter type	Parameter description
data.reqId	string	Value is CallAck.

{
    "data":{
        "reqId": "CallAck"
    }
}

Response data:

{
    "code": 0, // 0 indicates success, non-0 indicates failure
    "message": ""
}

12. Query electronic fences on the map through HTTP protocol

URL: GET http://localhost:8080/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
            }
        ]
    }
}

13. Search electronic fences through HTTP protocol

URL: GET http://localhost:8080/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
    }
}

14. Load some electronic fence through HTTP protocol

URL: GET http://localhost:8080/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
    }
}

14. Add electronic fence through HTTP protocol

URL: POST http://localhost:8080/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": ""
}

15. Update electronic fence through HTTP protocol

URL: PUT http://localhost:8080/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": ""
}

15. Delete electronic fence through HTTP protocol

URL: DELETE http://localhost:8080/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": ""
}