Appearance

Tag Device Integration Solution ​

Core Description ​

Tag device integration only supports location information synchronization and does not include alarm-related data for the time being. Two integration methods are introduced below, which can be selected according to business requirements.

1. OPEN API Integration ​

1.1 Applicable Scenarios ​

Customers subscribe to services through the TSP platform (supports 10min/60min data update frequencies), and actively obtain tag device location data by calling specified interfaces.

1.2 Reference Interfaces (Partial) ​

Detailed Documentation: https://tracksolidprodocs.jimicloud.com/

Interface PurposeInterface LinkMethod Name
Get Access Tokenhttps://tracksolidprodocs.jimicloud.com/integration/integration.html#_1-1-get-access-tokenjimi.oauth.token.get
Refresh Access Tokenhttps://tracksolidprodocs.jimicloud.com/integration/integration.html#_1-2-refresh-access-tokenjimi.oauth.token.refresh
Get Device Locations in Batch by Accounthttps://tracksolidprodocs.jimicloud.com/integration/integration.html#_3-1-get-location-of-devices-by-accountjimi.user.device.location.list
Get Single Device Locationhttps://tracksolidprodocs.jimicloud.com/integration/integration.html#_3-2-get-the-location-of-device-sjimi.device.location.get
Get Historical Trackhttps://tracksolidprodocs.jimicloud.com/integration/integration.html#_3-5-get-the-track-data-of-devicejimi.device.track.list
Manually Refresh Tag Real-Time Locationhttps://tracksolidprodocs.jimicloud.com/integration/integration.html#_3-8-get-the-location-of-tag-devicejimi.device.location.getTagMsg
Refresh Tag Data in Batchhttps://tracksolidprodocs.jimicloud.com/integration/integration.html#_3-9-refresh-tag-data-in-batchjimi.device.location.updateTagDevices

1.3 Location Information Update Mechanism ​

(1) Automatic Update (Default Mode) ​

  • Location data is automatically synchronized according to the update frequency subscribed on the TSP platform (10min/60min).
  • Call jimi.user.device.location.list or jimi.device.location.get to directly return the latest location data (updated periodically at the subscribed frequency; minimum interval: 10min).

(2) Manual Refresh (Force Data Acquisition) ​

  • To get the latest location immediately, first call jimi.device.location.getTagMsg or jimi.device.location.updateTagDevices to trigger a refresh.
  • After refresh, call jimi.user.device.location.list or jimi.device.location.get to obtain real-time synchronized data.

For a single device, the refresh interval is not recommended to be less than 10 minutes — this is because the TSP platform’s shortest data update frequency is fixed at 10 minutes. Even if you initiate more frequent refresh requests (e.g., within 10 minutes), the device’s location data will not be updated in advance, leading to redundant calls without additional valid information. Adhering to the 10-minute minimum interval ensures efficient use of API resources while meeting the actual data synchronization needs.

1.4 Call Frequency Limits ​

  • Key Limit: The maximum daily call count for jimi.device.location.getTagMsg and jimi.device.location.updateTagDevices is 8640 (actual limit subject to account scale).
  • Recommendation: Avoid frequent manual refreshes when managing a large number of tag devices to prevent exceeding limits and service unavailability.
  • Data Update Rule:

The TSP server pulls the latest positioning data at the subscribed interval (10min/60min). jimi.device.location.get and jimi.user.device.location.list return only the latest single location point. Example (10min cycle): Frequent calls within one hour yield at most 6 valid points; no extra data is generated. Call once every 10 minutes to meet requirements and reduce redundant requests. jimi.device.track.list retrieves historical tracks, which include all points collected in the 10-minute window. Use interfaces appropriately based on business logic.

2. GPS Data Push API Integration (Webhook Active Push) ​

TAG Pushes Data to Client ​

path: /api/v1/tag/data/push

Request method: POST

Content-Type: application/json

Request Field Description ​

FieldTypeDescription
gpsNumIntConfidence
gpsTimelongPositioning timestamp
imeiStringDevice IMEI
latdoubleLatitude
lngdoubleLongitude
positionTypeStringPositioning type

Request Example ​

json
[
    {
        "gpsNum": 3,
        "gpsTime": 1758722036000,
        "imei": "xxxxxxxxxxxxxxx",
        "lat": 22.576582,
        "lng": 113.94306,
        "positionType": "BEACON"
    },
    {
        "gpsNum": 3,
        "gpsTime": 1758722416000,
        "imei": "xxxxxxxxxxxxxxx",
        "lat": 22.57658,
        "lng": 113.94306,
        "positionType": "BEACON"
    }
]

Response Field Description ​

FieldTypeDescription
codeIntReturn 200 for successful reception; otherwise, data will be resent
msgStringResponse message

Response Example ​

json
{
    "code": 200,
    "msg": "success"
}

2.1 Core Purpose ​

Active push via Webhook: When the device reports a new location, the Jimi server automatically pushes data to the customer’s configured server URL. No polling is required, improving efficiency.

2.2 Development & Configuration Requirements ​

  1. Develop a receiver service per the API document; ensure the URL has stable public network accessibility for Webhook configuration.
  2. Device Ownership: If devices belong to multiple accounts, provide all associated accounts. Only data under configured accounts is pushed; sub-account data is not synced to the main account.
  3. URL Limits: One push URL per device (no duplicates); different accounts may use different URLs.

2.3 Data Push Rules (10min Subscription Example) ​

Push frequency depends on location updates (not fixed intervals):

  1. Continuous location updates: Push latest data every 10 minutes.
  2. No updates within 10 minutes: No push (avoids invalid transmission).
  3. Minimum interval: 10 minutes; shorter intervals are not supported.
  4. No retry mechanism for failed Webhook deliveries.

3. General Notes ​

  1. Data Scope: All integration methods only sync tag device location; alarm data is not supported.
  2. Authentication: TSP API requires token acquisition via jimi.oauth.token.get and timely refresh via jimi.oauth.token.refresh before expiration.
  3. Network: The GPS push receiver URL must be publicly accessible to avoid push failures due to firewalls or network issues.
Download

Last updated: