tracksolid_timescale_grafana_prod/tracksolidApiDocumentation.md

# Tracksolid Pro API Documentation

> Consolidated from official Jimi IoT documentation at [tracksolidprodocs.jimicloud.com](https://tracksolidprodocs.jimicloud.com/) and [docs.jimicloud.com](https://docs.jimicloud.com/integration/integration.html).
>
> API Spec Version: 2.7.7 | Last updated: 2026-04-08

---

## Table of Contents

1. [Overview](#1-overview)
2. [Authentication & Signing](#2-authentication--signing)
3. [Access Control](#3-access-control)
4. [Device Management](#4-device-management)
5. [Tracking & Telemetry](#5-tracking--telemetry)
6. [Alarms](#6-alarms)
7. [Media](#7-media)
8. [Command Management](#8-command-management)
9. [Geofencing](#9-geofencing)
10. [Data Push API (Webhooks)](#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](#2-authentication--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

```json
{
  "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

---

## 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 |
| `lat` | double | Latitude |
| `lng` | double | Longitude |
| `speed` | number | Speed (km/h) |
| `gpsTime` | string | GPS fix timestamp |
| `accStatus` | string | ACC ignition status |
| `currentMileage` | number | Odometer reading |
| `expireFlag` | string | Expiration flag |

---

### 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 in kilometers |
| `avgSpeed` | number | Average speed (km/h) |
| `runTimeSecond` | int | Trip duration in seconds |

---

### 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 |

---

### 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 type |

**Response (array):**

| Field | Type | Description |
|---|---|---|
| `imei` | string | Device IMEI |
| `startTime` | string | Parking/idle start |
| `endTime` | string | Parking/idle end |
| `durSecond` | int | Total duration (seconds) |
| `addr` | string | Address / location |
| `deviceName` | string | Device name |
| `stopSecond` | int | Stationary duration (seconds) |

---

### 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 |
| `alarmTypeName` | string | Alarm type display name |
| `alertTime` | string | Alarm trigger time |
| `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) |

> **Note:** The documented response field names (`alertTypeId`, `alertTime`) may differ from what some code examples use (`alarmType`, `alarmTime`). Always verify against actual API responses.

---

## 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` |
|---|---|

**`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` |
|---|---|

**`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` |
|---|---|

**`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` |
|---|---|

**`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 |
| `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` |
|---|---|

**`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` |
|---|---|

**`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` |
|---|---|

> **Important:** This is the only documented method for receiving OBD data. There is no polling/pull endpoint for OBD.

**`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` |
|---|---|

> **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` |
|---|---|

**`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

| API Method | Pipeline | Status |
|---|---|---|
| `jimi.oauth.token.get` | `ts_shared_rev.py` | In use |
| `jimi.oauth.token.refresh` | `ts_shared_rev.py` | In use |
| `jimi.user.device.list` | `ingest_movement_rev.py` | In use |
| `jimi.track.device.detail` | `ingest_movement_rev.py` | In use |
| `jimi.user.device.location.list` | `ingest_movement_rev.py` | In use |
| `jimi.device.track.mileage` | `ingest_movement_rev.py` | In use |
| `jimi.device.alarm.list` | `ingest_events_rev.py` | In use — field mapping corrected (FIX-E06) |
| `jimi.device.obd.list` | `ingest_events_rev.py` | **Not a real endpoint** — OBD is push-only |
| `jimi.device.track.list` | `ingest_movement_rev.py` | **In use** — poll_track_list() every 30m (FIX-M14) |
| `jimi.device.location.get` | `ingest_movement_rev.py` | **In use** — get_device_locations() on-demand (FIX-M15) |
| `jimi.open.platform.report.parking` | `ingest_movement_rev.py` | **In use** — acc_type/durSecond fixed (FIX-M13) |
| `jimi.device.jimi.media.URL` | — | Not used (media catalog) |
| `jimi.device.media.event.URL` | — | Not used (alarm-triggered media) |
| All Data Push endpoints | — | Not used (webhook receiver needed) |