tracksolid_timescale_grafana_prod/tracksolidApiDocumentation.md

Tracksolid Pro API Documentation

Consolidated from official Jimi IoT documentation at tracksolidprodocs.jimicloud.com and docs.jimicloud.com.

API Spec Version: 2.7.7 | Last updated: 2026-04-11

---

Table of Contents

1. Overview
2. Authentication & Signing
3. Access Control
4. Device Management
5. Tracking & Telemetry
6. Alarms
7. Media
8. Command Management
9. Geofencing
10. Data Push API (Webhooks)

---

1. Overview

Architecture

Your application server connects to the Jimi API server — client apps should never call the API directly. You must apply for an appKey and appSecret from Jimi (providing your account), then use your server to obtain an access_token and call other interfaces.

Conventions

• Encoding: UTF-8
• Format: JSON (application/json charset=utf-8)
• Timezone: UTC (GMT+0)
• Timestamp format: yyyy-MM-dd HH:mm:ss
• All requests use POST to a single base URL with the method parameter to differentiate endpoints

Regional Base URLs

Region	Base URL
TrackSolid (TS)	http://open.10000track.com/route/rest
TSP Hong Kong / Singapore	https://hk-open.tracksolidpro.com/route/rest
TSP Europe	https://eu-open.tracksolidpro.com/route/rest
TSP United States	https://us-open.tracksolidpro.com/route/rest

Common Request Parameters

Every API call includes these base parameters:

Parameter	Type	Required	Description
method	string	Yes	API method identifier (e.g. jimi.oauth.token.get)
app_key	string	Yes	Application key assigned by Jimi
timestamp	string	Yes	Current UTC time (yyyy-MM-dd HH:mm:ss)
sign_method	string	Yes	Always md5
sign	string	Yes	MD5 signature (see Signing)
v	string	Yes	API version, always 1.0
format	string	Yes	Always json
access_token	string	Conditional	Required for all methods except token acquisition

Common Response Structure

{
  "code": 0,
  "message": "success",
  "result": { }
}

Code	Meaning
0	Success
1004	Token expired — refresh or re-authenticate
1006	Rate limit exceeded — back off and retry
-1	General error

Rate Limits

• Token acquisition (jimi.oauth.token.get) can be called at most once per minute
• jimi.device.alarm.list — time range limited to 1 month, max 1000 rows returned
• Batch endpoints accept up to 50 IMEIs per call
• jimi.device.track.list — per-device endpoint (no batch); each call can be slow (~137s observed in production for a 35-minute lookback). Do not call synchronously inside a 60s scheduler loop; run on a dedicated 30-minute schedule.

---

2. Authentication & Signing

MD5 Signature Algorithm

Every API call requires a signature to prevent tampering. The algorithm:

1. Collect all request parameters (excluding sign and any with null values)
2. Sort parameters alphabetically by key
3. Concatenate as: {appSecret}{key1}{value1}{key2}{value2}...{appSecret}
4. Compute MD5 hash of the UTF-8 encoded string
5. Convert to uppercase hex

Example:

Input:  SECRET + "app_keyABC123methodjimi.oauth.token.gettimestamp2025-01-01 00:00:00" + SECRET
Output: MD5 → uppercase hex string

---

3. Access Control

3.1 Get Access Token

Obtain an authentication token for API access.

Method	jimi.oauth.token.get
Auth required	No (this obtains the token)
Rate limit	Max 1 call per minute

Parameters:

Parameter	Type	Required	Description
user_id	string	Yes	Account user ID
user_pwd_md5	string	Yes	MD5 hash of user password
expires_in	int	Yes	Token lifetime in seconds (e.g. 7200 for 2 hours)

Response:

Field	Type	Description
accessToken	string	The access token for subsequent API calls
expiresIn	int	Token lifetime in seconds
account	string	Account identifier
appKey	string	Application key
refreshToken	string	Token used to refresh before expiry
time	string	Server time

---

3.2 Refresh Access Token

Update token before it expires without full re-authentication.

Method	jimi.oauth.token.refresh
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
access_token	string	Yes	Current access token
refresh_token	string	Yes	Refresh token from initial auth
expires_in	int	Yes	New token lifetime in seconds

Response: Same as jimi.oauth.token.get.

---

4. Device Management

4.1 List All Devices

Retrieve all devices belonging to a specified account.

Method	jimi.user.device.list
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
target	string	Yes	Target account ID

Response (array):

Field	Type	Description
imei	string	Device IMEI
deviceName	string	Device display name
mcType	string	Device model type
sim	string	SIM card number
expiration	string	Service expiration date
activationTime	string	Device activation date
vehicleName	string	Assigned vehicle name
vehicleNumber	string	License plate / vehicle number
driverName	string	Assigned driver name
enabledFlag	int	1 = enabled, 0 = disabled

---

4.2 Get Device Detail

Retrieve comprehensive information for a specific IMEI.

Method	jimi.track.device.detail
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
imei	string	Yes	Device IMEI

Response:

Field	Type	Description
imei	string	Device IMEI
deviceName	string	Device name
account	string	Owner account
mcType	string	Model type
sim	string	SIM number
expiration	string	Service expiration
vehicleName	string	Vehicle name
currentMileage	number	Odometer reading
deviceGroup	string	Group name

---

4.3 Update Device Expiration

Modify device expiration dates.

Method	jimi.user.device.expiration.update
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
imei_list	string	Yes	Comma-separated IMEIs
new_expiration	string	Yes	New expiration date

Response:

Field	Type	Description
imei	string	Device IMEI
update_result	string	Result status
update_msg	string	Result message

---

4.4 Update Vehicle Information by IMEI

Update vehicle details and device settings.

Method	jimi.open.device.update
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
imei	string	Yes	Device IMEI
device_name	string	No	Device display name
vehicle_name	string	No	Vehicle name
vehicle_icon	string	No	Vehicle icon identifier
vehicle_number	string	No	License plate
driver_name	string	No	Driver name
driver_phone	string	No	Driver phone
device_status	string	No	Device status
sim	string	No	SIM card number
remarks	string	No	Notes
mileage	number	No	Current mileage

Response: Success confirmation (code 0).

---

4.5 Move Devices Between Accounts

Transfer devices between sub-accounts.

Method	jimi.open.device.move
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
src_account	string	Yes	Source account
dest_account	string	Yes	Destination account
imeis	string	Yes	Comma-separated IMEIs
cleanBindFlag	boolean	No	Clear existing bindings

Response:

Field	Type	Description
result	array	Array of moved device IMEIs

---

4.6 Bind App User

Associate device with a mobile application user.

Method	jimi.open.device.bind
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
imei	string	Yes	Device IMEI
user_id	string	Yes	App user ID

---

4.7 Unbind App User

Remove device association from a mobile application user.

Method	jimi.open.device.unbind
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
imei	string	Yes	Device IMEI
user_id	string	Yes	App user ID

---

4.8 Create Device Group

Method	jimi.device.group.create
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
account	string	Yes	Account ID
group_name	string	Yes	Group name

Response:

Field	Type	Description
group_id	string	Created group ID
group_name	string	Group name

---

4.9 Edit Device Group

Method	jimi.device.group.update
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
group_id	string	Yes	Group ID to edit
group_name	string	Yes	New group name

---

4.10 Delete Device Group

Method	jimi.device.group.delete
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
group_id	string	Yes	Group ID to delete

---

4.11 List Device Groups

Method	jimi.device.group.list
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
account	string	Yes	Account ID

Response (array):

Field	Type	Description
group_id	string	Group identifier
group_name	string	Group display name

---

5. Tracking & Telemetry

5.1 Get Location of Devices by Account

Retrieve latest positions for all devices under an account. Single API call for entire fleet.

Method	jimi.user.device.location.list
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
target	string	Yes	Target account ID
map_type	string	No	Coordinate system (e.g. GOOGLE)

Response (array):

Field	Type	Description
imei	string	Device IMEI
deviceName	string	Device name
status	string	Device status code
lat	double	Latitude
lng	double	Longitude
speed	number	Speed (km/h)
direction	number	Heading (0–360 degrees)
gpsTime	string	GPS fix timestamp
hbTime	string	Heartbeat/server receive time
accStatus	string	ACC ignition status (0=off, 1=on)
gpsSignal	int	GPS signal quality (0–4)
gpsNum	int	Satellites used
currentMileage	number	Odometer reading
powerValue	number	External power voltage
elecQuantity	number	Battery percentage
posType	string	Position type
confidence	int	Position confidence score
expireFlag	string	Subscription expiration flag
activationFlag	string	Activation status
locDesc	string	Reverse-geocoded address (if available)

Implementation note: This is the fleet sweep endpoint called every 60 seconds. In production it returns ~19 active devices out of 63 queried, averaging ~200ms per call. Devices without a current position are silently omitted from the response — they are not returned with null coordinates.

---

5.2 Get Location of Specific Device(s)

Fetch current position for one or multiple specific devices.

Method	jimi.device.location.get
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
imeis	string	Yes	Comma-separated IMEI list
map_type	string	No	Coordinate system

Response (array):

Field	Type	Description
imei	string	Device IMEI
deviceName	string	Device name
lat	double	Latitude
lng	double	Longitude
status	string	Device status
speed	number	Speed (km/h)
gpsTime	string	GPS fix timestamp
accStatus	string	ACC ignition status
currentMileage	number	Odometer

---

5.3 Get Sharing Location URL

Generate a shareable map link for device location display.

Method	jimi.device.location.URL.share
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
imei	string	Yes	Device IMEI

Response:

Field	Type	Description
URL	string	Shareable map URL

---

5.4 Get Mileage / Trip Data

Extract trip and distance records within a time period. Supports batching up to 50 IMEIs.

Method	jimi.device.track.mileage
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
imeis	string	Yes	Comma-separated IMEI list (max 50)
begin_time	string	Yes	Start time (yyyy-MM-dd HH:mm:ss)
end_time	string	Yes	End time (yyyy-MM-dd HH:mm:ss)
start_row	int	No	Pagination offset
page_size	int	No	Page size

Response (array):

Field	Type	Description
imei	string	Device IMEI
startTime	string	Trip start time
endTime	string	Trip end time
distance	number	Distance — stored as kilometres in DB (see note below)
avgSpeed	number	Average speed (km/h) — field name: avgSpeed
maxSpeed	number	Maximum speed (km/h) — field name: maxSpeed
runTimeSecond	int	Driving time (seconds)
idleSecond	int	Idle time (seconds)

Distance unit note (BUG-02): The raw distance value returned by this endpoint is in kilometres as labelled. However, the value was being stored incorrectly as millimetres due to an erroneous × 1000 multiplication in earlier code. Migration 04 corrected all historical rows: distance_km = stored_value / 1,000,000. Current code stores distance directly as distance_km with no further conversion. The DB column was renamed from distance_m to distance_km to reflect this.

maxSpeed note (BUG-03): maxSpeed was present in the API response but not mapped in poll_trips(). Fixed — now stored in tracksolid.trips.max_speed_kmh.

---

5.5 Get Track Data (GPS Trail)

Retrieve detailed positional waypoints for a specified timeframe. Per-device endpoint.

Method	jimi.device.track.list
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
imei	string	Yes	Single device IMEI
begin_time	string	Yes	Start time (yyyy-MM-dd HH:mm:ss)
end_time	string	Yes	End time (yyyy-MM-dd HH:mm:ss)
map_type	string	No	Coordinate system

Response (array):

Field	Type	Description
lat	double	Latitude
lng	double	Longitude
gpsTime	string	Timestamp of GPS fix
gpsSpeed	int	Speed (km/h)
direction	int	Heading (0–360 degrees)
ignition	string	Ignition state
accStatus	string	ACC status
confidence	int	Position confidence
altitude	int	Altitude (metres) — not populated by all device models
satellite	int	Satellite count

Implementation note (POLL-01): Called per-device every 30 minutes with a 35-minute lookback window. Results written to tracksolid.position_history with source='track_list' (vs source='poll' for the 60s sweep). Use ON CONFLICT DO NOTHING — duplicate fixes from overlapping windows are safely discarded. Observed: ~5–6 waypoints per active device per 30-min window. Altitude field is returned but not populated by X3 and GT06E devices in this fleet.

---

5.6 Wi-Fi / Base Station Locating

Determine position using cellular tower and wireless network signals (fallback when GPS unavailable).

Method	jimi.lbs.address.get
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
imei	string	Yes	Device IMEI
lbs	string	No	LBS data
wifi	string	No	WiFi data

Response:

Field	Type	Description
lat	double	Latitude
lng	double	Longitude
accuracy	number	Position accuracy (meters)

---

5.7 Get Parking / Idling Data

Analyze stationary and engine-running periods.

Method	jimi.open.platform.report.parking
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
account	string	Yes	Account ID
imeis	string	Yes	Comma-separated IMEI list
start_time	string	Yes	Start time
end_time	string	Yes	End time
start_row	int	Yes	Pagination offset
page_size	int	Yes	Page size
acc_type	string	Yes	ACC filter: 0 = all stops, 1 = ignition-off only

Response (array):

Field	Type	Description
imei	string	Device IMEI
startTime	string	Parking/idle start
endTime	string	Parking/idle end
durSecond	int	Total duration (seconds) — use this field for duration
stopSecond	int	Stationary-only duration (seconds) — may be absent
addr	string	Address / location
deviceName	string	Device name

Implementation note (POLL-02): Pass acc_type=0 to capture all stop events (not just ignition-off). If acc_type is omitted or set to an empty string the API returns 0 rows. The primary duration field is durSecond; stopSecond is a secondary field that may not be populated. In production: 60 calls logged, all successful, 0 rows — expected while fleet is overnight-parked. Will populate once vehicles complete a full stop–start–stop cycle.

---

5.8 Get Location of TAG Device

Query latest beacon/TAG positioning data.

Method	jimi.device.location.getTagMsg
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
imei	string	Yes	TAG device IMEI

Response:

Field	Type	Description
lng	double	Longitude
lat	double	Latitude
gpsTime	string	GPS timestamp
gpsSpeed	int	Speed
positionType	string	Position method
gpsNum	int	Satellite count

---

6. Alarms

6.1 Get Device Alarm List

Retrieve alarm events for devices within a time range.

Method	jimi.device.alarm.list
Auth required	Yes
Constraints	Time range max 1 month, max 1000 rows returned

Parameters:

Parameter	Type	Required	Description
imeis	string	Yes	Comma-separated IMEI list
begin_time	string	Yes	Start time (yyyy-MM-dd HH:mm:ss)
end_time	string	Yes	End time (yyyy-MM-dd HH:mm:ss)
page_size	int	No	Results per page (max 1000)

Response (array):

Field	Type	Description
deviceName	string	Device name
imei	string	Device IMEI
model	string	Device model
account	string	Account
alertTypeId	string	Alarm type identifier — polling field name
alarmTypeName	string	Alarm type display name — polling field name
alertTime	string	Alarm trigger time — polling field name
positioningTime	string	GPS fix time at alarm
lat	double	Latitude
lng	double	Longitude
speed	number	Speed at alarm time
geoid	string	Geo-fence ID (if geofence alarm)

Critical field name difference — polling vs push (BUG-01):

Data	Polling (jimi.device.alarm.list)	Push (/pushalarm)	DB column
Type ID	alertTypeId	alarmType	alarm_type
Type name	alarmTypeName	alarmName	alarm_name
Time	alertTime	gateTime	alarm_time

Earlier code used the push field names (alarmType, alarmName) in the polling path — these keys are never present in the polling response, so alarm_type and alarm_name were always NULL. Fixed in ingest_events_rev.py (FIX-E06): polling now maps item.get('alertTypeId') → alarm_type and item.get('alarmTypeName') → alarm_name. Verified in production: vibration alarms now store type 3 and name "Vibration alert" correctly.

---

7. Media

7.1 Get Device Live Streaming Page URL

Provides an embeddable URL for real-time video broadcast.

Method	jimi.device.live.page.url
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
imei	string	Yes	Device IMEI
type	string	No	Stream type
voice	string	No	Audio toggle

Response:

Field	Type	Description
lat	double	Device latitude
lng	double	Device longitude
gpsTime	string	GPS time
VIN	string	Vehicle VIN
plateNo	string	Plate number
UrlCamera	string	Embeddable streaming page URL

---

7.2 Send Media Instruction (Capture Photo/Video)

Command a DVR device to capture video or still images on demand.

Method	jimi.device.meida.cmd.send
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
imei	string	Yes	Device IMEI
camera	int	Yes	Camera channel index
mediaType	string	Yes	photo or video
shootTime	int	No	Video recording duration (seconds)

Response:

Field	Type	Description
code	int	Result code
msg	string	Result message
cmdSeqNo	string	Command sequence number for tracking

---

7.3 Send History Video Instruction

Command device to upload recorded video files from its storage.

Method	jimi.device.history.cmd.send
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
imei	string	Yes	Device IMEI
type	string	Yes	Upload type
camera	int	Yes	Camera channel
fileName	string	No	Specific file name
time	string	No	Time filter

Response:

Field	Type	Description
code	int	Result code
msg	string	Result message
cmdSeqNo	string	Command sequence number

---

7.4 Get Device Photo/Video URL

Retrieve URLs for captured photos and video recordings.

Method	jimi.device.jimi.media.URL
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
imei	string	Yes	Device IMEI
camera	int	Yes	Camera channel
media_type	string	Yes	photo or video
start_time	string	No	Filter start time
end_time	string	No	Filter end time
token	string	No	Pagination token
page_no	int	No	Page number
page_size	int	No	Results per page

Response (array):

Field	Type	Description
thumb_URL	string	Thumbnail URL
file_URL	string	Full file download URL
create_time	string	Capture timestamp
mime_type	string	MIME type (image/jpeg, video/mp4, etc.)
camera	int	Camera channel
file_size	int	File size in bytes

---

7.5 Get Device Media Event URL

Retrieve media files triggered by alarm events (hard braking, collision, etc.).

Method	jimi.device.media.event.URL
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
imeis	string	Yes	Comma-separated IMEI list
media_type	string	Yes	photo or video
start_time	string	Yes	Filter start time
end_time	string	Yes	Filter end time
page_no	int	Yes	Page number
page_size	int	Yes	Results per page
event_type	string	No	Filter by event type

Response (array):

Field	Type	Description
imei	string	Device IMEI
event_type	string	Alarm/event type
lat	double	Latitude at event
lng	double	Longitude at event
alarm_time	string	Event timestamp
fileList	array	Nested array of file objects (URLs, MIME types, sizes)

---

7.6 Get Device Live Streaming Address

Obtain a streaming protocol address (RTSP/HLS) for real-time video.

Method	jimi.device.media.live.stream
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
imei	string	Yes	Device IMEI
channel	int	Yes	Camera channel (1-5)
appId	string	Yes	Application identifier

Response:

Field	Type	Description
result	string	Streaming URL

---

7.7 Send Command to Query Historical Video List

Two-step process: first send this command to prompt the device to compile its stored video inventory.

Method	jimi.device.media.history.list.cmd
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
imei	string	Yes	Device IMEI
channel	int	Yes	Camera channel
dateTime	string	Yes	Target date/time
instructionId	string	Yes	Unique instruction identifier
appId	string	Yes	Application identifier

Response: Acknowledgment only.

---

7.8 Query Historical Video List

Second step: retrieve the compiled video file metadata (after sending 7.7).

Method	jimi.device.media.history.list.get
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
instructionId	string	Yes	Same ID used in 7.7

Response (array):

Field	Type	Description
channel	int	Camera channel
beginTime	string	Recording start time
endTime	string	Recording end time
fileSize	int	File size
fileName	string	File name
codeType	int	Encoding type (1=Main, 2=Sub)

---

7.9 Get Historical Video Streaming Address

Generate a playback URL for recorded video segments.

Method	jimi.device.media.history.stream
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
imei	string	Yes	Device IMEI
channel	int	Yes	Camera channel
appId	string	Yes	Application identifier
beginTime	string	No	Playback start time
endTime	string	No	Playback end time
fileNameList	string	No	Specific file names

Response:

Field	Type	Description
result	string	Playback streaming URL

---

7.10 Close Streaming

Terminate an active video streaming session to release resources.

Method	jimi.device.media.close.stream
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
imei	string	Yes	Device IMEI
channel	int	Yes	Camera channel
type	string	Yes	Stream type to close
appId	string	Yes	Application identifier

---

8. Command Management

8.1 Get Command List Supported by Device

Retrieve available command templates for a target device model.

Method	jimi.open.instruction.list
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
imei	string	Yes	Device IMEI

Response (array):

Field	Type	Description
id	string	Command template ID
orderName	string	Command name
orderContent	string	Command template
orderExplain	string	Description
isOffLine	boolean	Supports offline delivery

---

8.2 Send Command to Device

Transmit a formatted instruction with substituted parameters.

Method	jimi.open.instruction.send
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
imei	string	Yes	Device IMEI
inst_param_json	string	Yes	JSON-encoded command parameters

---

8.3 Get Results of Command Execution

Retrieve execution status and device response for a sent command.

Method	jimi.open.instruction.result
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
imei	string	Yes	Device IMEI

Response (array):

Field	Type	Description
codeId	string	Command ID
code	string	Command code
content	string	Device response content
isExecute	boolean	Whether executed
sendTime	string	Send timestamp
sender	string	Who sent
receiveDevice	string	Target device

---

8.4 Send Raw Command Data

Transmit hexadecimal command directly to device (advanced usage).

Method	jimi.open.instruction.raw.send
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
imei	string	Yes	Device IMEI
raw_cmd	string	Yes	Hex-encoded command data

---

9. Geofencing

9.1 Create Device Geo-fence

Establish a circular boundary alarm directly on the device.

Method	jimi.open.device.fence.create
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
imei	string	Yes	Device IMEI
fence_name	string	Yes	Fence display name
alarm_type	string	Yes	Alarm trigger type
report_mode	string	Yes	Reporting mode
alarm_switch	string	Yes	Enable/disable
lng	double	Yes	Center longitude
lat	double	Yes	Center latitude
radius	int	Yes	Radius in meters
zoom_level	int	Yes	Map zoom level
map_type	string	Yes	Map coordinate system

Response:

Field	Type	Description
result	string	Fence serial number

---

9.2 Delete Device Geo-fence

Method	jimi.open.device.fence.delete
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
imei	string	Yes	Device IMEI
instruct_no	string	Yes	Fence serial number

---

9.3 Create Platform Geo-fence

Establish a server-side boundary definition (supports polygons, circles, etc.).

Method	jimi.open.platform.fence.create
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
account	string	Yes	Account ID
fence_name	string	Yes	Fence name
fence_type	string	Yes	Geometry type
geom	string	Yes	Geometry definition (GeoJSON or WKT)
fence_color	string	No	Display color
radius	int	No	Radius (for circle type)
description	string	No	Description

Response:

Field	Type	Description
data	string	Created fence ID

---

9.4 Delete Platform Geo-fence

Method	jimi.open.platform.fence.delete
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
account	string	Yes	Account ID
fence_id	string	Yes	Fence ID to delete

---

9.5 Bind Devices to Platform Geo-fence

Associate devices with a server boundary and configure alert triggers.

Method	jimi.open.platform.fence.bind
Auth required	Yes

Parameters:

Parameter	Type	Required	Description
fence_id	string	Yes	Fence ID
imeis	string	No	Comma-separated IMEIs
alert_type	string	No	Alert trigger (enter/exit/both)
stay_time_in	int	No	Dwell time threshold for entry (seconds)
stay_time_out	int	No	Dwell time threshold for exit (seconds)

Response:

Field	Type	Description
data	int	Count of related devices

---

10. Data Push API (Webhooks)

The Data Push API is a server-to-server push architecture where Jimi's servers POST data to your HTTP endpoints. This is the primary mechanism for receiving real-time telemetry and the only way to receive certain data types (OBD, fault codes, heartbeat).

You must configure your callback URL in the Tracksolid Pro platform. All push endpoints use:

• Method: POST
• Content-Type: application/x-www-form-urlencoded
• Common parameters: token (string) and data_list (JSON string array, max 50 items per request)
• Expected response: {"code": 0, "msg": "success"}

---

10.1 Login/Logout Events

Endpoint	{YourURL}/pushevent
Handler	webhook_receiver_rev.py — implemented (PUSH-01)
DB table	tracksolid.device_events

data_list fields:

Field	Type	Description
deviceImei	string	Device IMEI
type	string	LOGIN or LOGOUT
gateTime	string	Event time (yyyy-MM-dd HH:mm:ss)
timezone	string	Device timezone (e.g. GMT+08:00)

---

10.2 Heartbeat Data

Endpoint	{YourURL}/pushhb
Handler	Not yet implemented — DB table tracksolid.heartbeats exists and is ready

data_list fields (max 50 per request):

Field	Type	Description
deviceImei	string	Device IMEI
gateTime	string	Heartbeat time
powerLevel	int	Battery percentage
gsmSign	int	GSM signal strength
acc	int	ACC status (0=OFF, 1=ON)
powerStatus	int	0=Not charging, 1=Charging
fortify	int	Defense/fortify status

---

10.3 GPS Data

Endpoint	{YourURL}/pushgps

data_list fields (max 50 per request):

Field	Type	Description
deviceImei	string	Device IMEI
gpsTime	string	GPS fix time
gateTime	string	Server receive time
lng	double	Longitude
lat	double	Latitude
satelliteNum	int	Satellites used
gpsSpeed	int	Speed (km/h)
direction	int	Heading (0-360 degrees)
acc	int	ACC status
postType	int	1=GPS, 2=LBS, 3=WiFi
postMethod	int	Upload mode (0x00-0x0F)
status	int	Position status flags
altitude	int	Altitude (meters)
distance	int	Mileage (meters)

---

10.4 Alarm Data

Endpoint	{YourURL}/pushalarm
Handler	webhook_receiver_rev.py — implemented
DB table	tracksolid.alarms

Field name note: Push uses alarmType and alarmName — different from the polling endpoint which uses alertTypeId and alarmTypeName. See Section 6.1 for the full mapping table.

data_list fields (max 50 per request):

Field	Type	Description
deviceImei	string	Device IMEI
alarmType	string	Alarm type
alarmName	string	Alarm display name
gateTime	string	Event time
(additional fields vary by alarm type)

---

10.5 RFID Data

Endpoint	{YourURL}/rfid

data_list fields:

Field	Type	Description
moduleType	string	RFID module type
deviceImei	string	Device IMEI
gateTime	string	Scan time
postTime	string	Post time
value	string	Encoded RFID value
gpsTime	string	Optional GPS time
lng, lat	double	Optional GPS position

---

10.6 Plug-In Module Data

Endpoint	{YourURL}/wgtc

data_list fields:

Field	Type	Description
deviceImei	string	Device IMEI
hexContent	string	Hex-formatted module data
postTime	string	Optional timestamp
gpsTime	string	Optional GPS time
lng, lat	double	Optional GPS position
category	string	Protocol (0x9B, 0xF2)
type	int	Message type

---

10.7 Fuel / Oil Sensor Data

Endpoint	{YourURL}/pushoil
Handler	webhook_receiver_rev.py — implemented (PUSH-02)
DB table	tracksolid.fuel_readings (TimescaleDB hypertable)

data_list fields (max 50 per request):

Field	Type	Description
deviceImei	string	Device IMEI
path	int	Sensor ID
gateTime	string	Reading time
value	double	Oil level (divide by 100 for actual value)
unit	int	1=cm, 2=%, 3=V, 4=L — stored as text label in DB
gpsTime	string	Optional GPS time
lng, lat	double	Optional GPS position

---

10.8 File Upload Notification

Endpoint	{YourURL}/pushfileupload

data_list fields:

Field	Type	Description
deviceImei	string	Device IMEI
fileName	string	File list (semicolon-separated)
gateTime	string	Upload time
result	string	SUCCESS or FAILURE

---

10.9 Temperature & Humidity

Endpoint	{YourURL}/pushtem
Handler	webhook_receiver_rev.py — implemented (PUSH-03)
DB table	tracksolid.temperature_readings (TimescaleDB hypertable)

data_list fields:

Field	Type	Description
deviceImei	string	Device IMEI
tem	double	Temperature value
hum	double	Humidity percentage
gateTime	string	Reading time
postTime	string	Post time

---

10.10 LBS / Cell Tower Data

Endpoint	{YourURL}/pushlbs
Handler	webhook_receiver_rev.py — implemented (PUSH-04)
DB table	tracksolid.lbs_readings

data_list fields:

Field	Type	Description
postType	string	WIFI or LBS
deviceImei	string	Device IMEI
gateTime	string	Reading time
lbsJson	string	JSON with MCC, MNC, cellList (LAC, CI, RSSI)

---

10.11 Resource List (Video Inventory)

Endpoint	{YourURL}/pushresourcelist

data_list fields:

Field	Type	Description
imei	string	Device IMEI
totalNum	string	Number of resources
instructionID	string	Unique instruction ID
resourceList	array	Objects with: channel, beginTime, endTime, fileSize, resourceType, codeType, storageType, alarmFlag

---

10.12 FTP Upload Result

Endpoint	{YourURL}/pushftpfileupload

data_list fields:

Field	Type	Description
result	int	0=Success, 1=Failure
deviceImei	string	Device IMEI
instructionID	string	Instruction reference
gateTime	string	Completion time

---

10.13 IoTHub Events

Endpoint	{YourURL}/pushIothubEvent

data_list fields:

Field	Type	Description
deviceImei	string	Device IMEI
gateTime	string	Event time
eventType	string	One of: UploadAlarmFileList, UploadAlarmFileBegin, UploadAlarmFileEnd, UploadMediaFileBegin, UploadMediaFileEnd
eventContent	string	Event-specific JSON payload

---

10.14 PassThrough Data

Endpoint	{YourURL}/pushPassThroughData

data_list fields:

Field	Type	Description
deviceImei	string	Device IMEI
gateTime	string	Receive time
type	int	Message type (0, 11, 65, 66, 240-255)
category	string	Protocol (0x0900, 0x9C, 0x94)
content	string	Base64-encoded message body

---

10.15 Extension Data

Endpoint	{YourURL}/pushTerminalTransInfo

data_list fields:

Field	Type	Description
postTime	string	Post time
deviceImei	string	Device IMEI
gpsTime	string	Optional GPS time
lng, lat	double	Optional GPS position
extensionId	int	8197=device status, 8199=serial port data
content	string	Extension-specific JSON

---

10.16 Offline Command Response

Endpoint	{YourURL}/pushInstructResponse

Fields:

Field	Type	Description
token	string	Auth token
msgType	int	1=Asynchronous, 2=Offline commands
data_list	string	JSON with _code, _msg, _imei, _serverFlagId, _content

---

10.17 Facial ID List

Endpoint	{YourURL}/pushFileContent

data_list fields:

Field	Type	Description
instructionId	string	Instruction reference
postTime	string	Post time
deviceImei	string	Device IMEI
gateTime	string	Event time
content	array	ID list strings

---

10.18 Extended Data (JIMI KKS)

Endpoint	{YourURL}/pushextendedkks

Pushes extended device data with sub-message types identified by subMessagesId:

• GPS data, KC208 events, power info, Bluetooth peripherals, positioning method, distance, ACC, LBS, pass-through data, positional accuracy

---

10.19 DVR Upload Callback

Endpoint	{YourURL}/uploadCallback

Called when a device finishes uploading media (photo, video, event clip) to Jimi's cloud.

data_list fields:

Field	Type	Description
businessType	string	regularPicture, remotePictureOrVideo, eventAttachment, historyVideo, facePicture, etc.
imei	string	Device IMEI
camera	int	Camera channel index
shootType	int	1=Photo, 2=Video
shootTime	int	Video duration (seconds)
alarmTime	long	Unix timestamp of alarm trigger
lat, lng	string	GPS coordinates
mimeType	string	image/jpeg, video/mp4, etc.
localFileName	string	Original device filename
filename	string	Cloud storage filename
timezone	string	Optional timezone
instructionId	string	Optional instruction reference

---

10.20 OBD Data

Endpoint	{YourURL}/pushobd
Handler	webhook_receiver_rev.py — implemented
DB table	tracksolid.obd_readings

Important: This is the only documented method for receiving OBD data. There is no polling/pull endpoint for OBD. The handler extracts scalar fields (engine_rpm, coolant_temp_c, fuel_level_pct, battery_voltage, intake_pressure, throttle_pct, vehicle_speed, engine_load_pct) from obdJson using well-known OBD PID dataID keys, and also stores the full obdJson in the obd_data JSONB column.

data_list fields:

Field	Type	Description
deviceImei	string	Device IMEI
obdJson	object	Contains all OBD readings
obdJson.car_type	int	1=Commercial, 2=Passenger
obdJson.push_time	string	Push timestamp
obdJson.event_time	string	Event timestamp
obdJson.AccState	int	0=OFF, 1=ON
obdJson.statusFlags	int	Status bit flags
obdJson.lng	double	Longitude
obdJson.lat	double	Latitude
obdJson.dataID1..N	int	Vehicle parameter values (engine RPM, coolant temp, fuel level, etc.)

---

10.21 DTC Fault Codes

Endpoint	{YourURL}/pushfaultinfo
Handler	Not yet implemented — DB table tracksolid.fault_codes exists and is ready

Important: This is the only documented method for receiving DTC fault codes.

data_list fields:

Field	Type	Description
deviceImei	string	Device IMEI
gateTime	string	Report time (yyyy-MM-dd HH:mm:ss)
faultCodeList	array	DTC codes (e.g. ["P0301", "P0420"])
faultNum	int	Number of fault codes
statusFlags	int	OBD status bit flags
lng	double	GPS longitude
lat	double	GPS latitude
eventTime	long	Fault event timestamp (Unix)

---

10.22 Trip Report

Endpoint	{YourURL}/pushtripreport
Handler	webhook_receiver_rev.py — implemented
DB table	tracksolid.trips

data_list fields:

Field	Type	Description
deviceImei	string	Device IMEI
gateTime	string	Report time
miles	double	Distance (km)
oils	double	Fuel consumption (L)
idleTimes	int	Accumulated idle time (seconds)
tripSeq	int	Trip sequence number
beginTime	string	Trip start (BCD format)
endTime	string	Trip end (BCD format)
beginLat, beginLng	double	Start coordinates
endLat, endLng	double	End coordinates
properties	int	1=Start, 2=End

---

Appendix A: Instruction API (sendInstruct)

For advanced device control, the instruction API uses a separate endpoint:

Endpoint: {InsAddress}/api/device/sendInstruct (POST)

Common parameters: deviceImei, proNo (protocol number), cmdContent (JSON), token

proNo	Function	Key cmdContent Fields
128	Universal text command	cmdContent (command string), sync, offlineFlag, timeOut
37121	Start real-time A/V stream	dataType, codeStreamType, channel, videoIP, videoTCPPort
37122	Control A/V stream	channel, cmd (0=Off, 1=Switch, 2=Pause, 3=Resume), dataType
37381	Query on-device video list	channel, beginTime, endTime, alarmFlag, resourceType, instructionID
37377	Start video playback	serverAddress, tcpPort, channel, beginTime, endTime, playMethod, instructionID
33283	Acknowledge alarm	alarmSerialNo

Response codes (data._code):

Code	Meaning
100	Success
200	Invalid parameter
300	Device offline
600	Timeout

---

Appendix B: API Coverage in This Codebase

Polling (Pull) Endpoints

API Method	File	Status	Notes
jimi.oauth.token.get	ts_shared_rev.py	✅ In use	Token auto-refreshed, cached in DB
jimi.oauth.token.refresh	ts_shared_rev.py	✅ In use
jimi.user.device.list	ingest_movement_rev.py	✅ In use	Fleet sync every 5h; 2 runs, 126 devices synced
jimi.track.device.detail	ingest_movement_rev.py	✅ In use	Called alongside device.list
jimi.user.device.location.list	ingest_movement_rev.py	✅ In use	Every 60s; 311 calls, 5,909 upserts, 0 failures
jimi.device.track.mileage	ingest_movement_rev.py	✅ In use	Trip polling; maxSpeed now mapped (BUG-03 fixed)
jimi.device.track.list	ingest_movement_rev.py	✅ In use	poll_track_list() every 30m (POLL-01 / FIX-M14); 15 calls, 80 waypoints
jimi.device.location.get	ingest_movement_rev.py	✅ In use	get_device_locations() on-demand batch refresh (POLL-03 / FIX-M15); max 50 IMEIs/call
jimi.open.platform.report.parking	ingest_movement_rev.py	✅ In use	acc_type=0, durSecond corrected (POLL-02 / FIX-M13); 60 calls, 0 rows (fleet overnight)
jimi.device.alarm.list	ingest_events_rev.py	✅ In use	alertTypeId/alarmTypeName mapping fixed (BUG-01 / FIX-E06); 11 calls, 11 rows
jimi.device.obd.list	—	❌ Does not exist	OBD data is push-only via /pushobd
jimi.device.jimi.media.URL	—	Not used	Media file catalog
jimi.device.media.event.URL	—	Not used	Alarm-triggered media
All other geofence/command/media polling	—	Not used	Available when needed

Push (Webhook) Endpoints

Endpoint	File	Status	DB Table
/pushalarm	webhook_receiver_rev.py	✅ Implemented	tracksolid.alarms
/pushtripreport	webhook_receiver_rev.py	✅ Implemented	tracksolid.trips
/pushobd	webhook_receiver_rev.py	✅ Implemented	tracksolid.obd_readings
/pushevent	webhook_receiver_rev.py	✅ Implemented (PUSH-01)	tracksolid.device_events
/pushoil	webhook_receiver_rev.py	✅ Implemented (PUSH-02)	tracksolid.fuel_readings
/pushtem	webhook_receiver_rev.py	✅ Implemented (PUSH-03)	tracksolid.temperature_readings
/pushlbs	webhook_receiver_rev.py	✅ Implemented (PUSH-04)	tracksolid.lbs_readings
/pushhb	—	⚠️ Not yet wired	tracksolid.heartbeats table ready
/pushfaultinfo	—	⚠️ Not yet wired	tracksolid.fault_codes table ready
/pushgps	—	Not used	GPS data received via polling
All other push endpoints	—	Not used

Registration status: All implemented webhook endpoints need to be registered in the Tracksolid Pro dashboard with your server's public URL before they will receive data. Tables exist and are ready; rows will be 0 until registration is complete.