Application

Dealers have their own system and would like to expand relevant GPS function. The customer account of the dealer is managed by the dealer's own system and is used to log in to the dealer's system. Dealer system account and the car online platform account is managed by dealer. Dealer use the car online platform account to get the related data. IMEI is managed by dealer’s own system and dealer can get data by IMEI. Distributor’s application server calling API.

Usage

To get appKey adn appSecret, distirbutors need to provide their account and password. Calling api interface by appkey and appSecret to obtain access_token. Distributor use the access_token to acquire data needed to visit OPEN API in Application Server.

Protocol format

Public convention

Convention


Context-Type:default
The API use UTC time in default: format
                    

public attributes of returned data

Parameter Type Required or not Description
code int Yes result code
message string No Code description

Code explanation

code Value Description
-1 -1 The system is busy
0 0 success
1xxx 1001 Parameter error (lack of required parameters or format error). See interface description for details
1002 Illegal user/illegal device (not their own or subordinate account or device)
10003 Repeat operation
1004 Illegal access, token exception! (Token failure or nonexistent)
1005 Illegal access, ip access exceeds limit!
1006 Illegal access, too frequently request!
1007 Illegal access, request method error!
1008 Illegal access, abnormal incoming!
12001 platform account creation failed
12002 device transfer failed
12003 geo-fence creation failed
12004 geo-fence deletion failed
12005 Fail to send command

Error code:

business code Description
create account 213 Account already exists
214 Account does not exist
215 User type error. Possible reasons: 1, the new user type is empty; 2, new user type does not exist; 3, the current login users do not have permission to create the new type of users
device transfer 217 Target user does not exist
218 User can only transfer/sale devices to sub-account
219 Imei list is illegal
220 imei number exceeds limit
geo-fence 41001 Exceed max number of geo-fences supported
41002 Fence name already exists
41003 The device is not online
41004 Geo-fence operation failed
Command 225 time out
226 Parameter error
227 The command is not executed correctly
228 The device is not online
229 Network error, connection error, etc.
238 Device interrupted
240 Data error
243 Not supportedbydevice
252 The device is busy

Communication flow

API data flow

API List

Interface type Method Parameter Name Description
Certification API jimi.oauth.token.get Get access_token
jimi.oauth.token.refresh Refresh access_token
User API jimi.user.child.create Create sub-account for designated account
jimi.user.child.list Check all subaccount information under the account
jimi.user.device.list Check all device information under the account
jimi.user.device.location.list Check the latest location information for all devices under the account
Device API jimi.device.location.get Get the latest location data based on IMEI
jimi.device.track.list Obtaintrack data according to IMEI
jimi.open.device.bind Bind users for device IMEI
jimi.open.device.unbind Unbind users for device IMEI
jimi.open.device.update Modify the vehicle information for the equipment IMEI
jimi.open.device.move device transfer
Command API jimi.open.instruction.list Gets command list supported by the device
jimi.open.instruction.send Designated device send command
jimi.open.instruction.result Getthe result of sent command
Geo-fence API jimi.open.device.fence.create Create an geo fence for the device IMEI
jimi.open.device.fence.delete Remove the geo fence for the device IMEI
LBS-API jimi.lbs.address.get Wifi, base station location analysis
Message jimi.push.device.alarm Push alerts notification

Protocol details

Call entry

Call URL of API. All interfaces use this URL.

Call environment (HTTP)
Overseas formal environment http://open.10000track.com/route/rest

Authentication

User get access_token by appkey and appSecret, which are provided by JIMI platform. Incoming appkey and access_token needed and request parameters should be signed when call API. JIMI server will authenticate the request parameters.

Common params

Name Type Required or not Description Value description Default values
method String Yes API interface name
timestamp String Yes Timestamp, format:yyyy-MM-dd HH:mm:ss. Plus or minus10 minutes is allowed. e.g:2012-03-25 20:00:00
app_key String Yes APP_KEY distributed by JIMI Correspond to company level, only one
sign String Yes API input parameters signature result
sign_method String Yes Optional, specify the signature method. System default md5, support methods are: md5 md5 md5
v String Yes Optional, specify the API version. System default 1.0, support version: 0.9,1.0 0.9:give up signature validation1.0:do signature validation
format String Yes Optional, specify response format. default::json json

API signature

To prevent the API call hacked by hackers, any API calling needs be with a signature. TOP server will authenticate signature based on request parameters. Illegal signature request will be rejected. Signature algorithms supported by TOP are: MD5 (sign_Method value in common parameters ismd5),The general process of signature is as follows:

• Sort all API requested parameters based on ASCII of parameters names (including common parameters and business parameters, but excluding sign and byte parameter. For example: foo=1, bar=2, foo_bar=3, foobar=4. Order sorted is bar=2, foo=1, foo_bar=3, foobar=4

• Put all parameter names and values together, the result isbar2foo1foo_bar3foobar4

• The assembled string use utf-8 encoding. Use signature algorithm to abstract compiled byte stream . If use the MD5 algorithm, you need to add app and secret before abstract. E.g:md5(secret+bar2foo1foo_bar3foobar4+secret)

• Byte stream is showed in hexadecimal. For example: hex(“helloworld”.getBytes(“utf-8”)) = “68656C6C6F776F726C64”


Description: MD5 is the 128-bit summary algorithm and is in hexadecimal. a hexadecimal character can represent four bits, so the signature string length is 32 hexadecimal characters.

algorithm

JAVA example:


public static String signTopRequest(Map params, String secret, String signMethod) throws IOException {
    // 1:Check whether the parameters have been sorted
    String[] keys = params.keySet().toArray(new String[0]);
    Arrays.sort(keys);
 
        // 2:: Put all parameter names and parameter values together
    StringBuilder query = new StringBuilder();
    if ("md5".equals(signMethod)) {
        query.append(secret);
    }
    for (String key : keys) {
        String value = params.get(key);
        if (StringUtils.areNotEmpty(key, value)) {
            query.append(key).append(value);
        }
    }
 
    // 3: use MD5/HMAC to encrypt
    byte[] bytes;
    if ("hmac".equals(signMethod)) {
        bytes = encryptHMAC(query.toString(), secret);
    } else {
        query.append(secret);
        bytes = encryptMD5(query.toString());
    }
 
    // 4: convert binary to uppercase hexadecimal
    return byte2hex(bytes);
}
 
public static byte[] encryptHMAC(String data, String secret) throws IOException {
    byte[] bytes = null;
    try {
        SecretKey secretKey = new SecretKeySpec(secret.getBytes("UTF-8"), "HmacMD5");
        Mac mac = Mac.getInstance(secretKey.getAlgorithm());
        mac.init(secretKey);
        bytes = mac.doFinal(data.getBytes("UTF-8"));
    } catch (GeneralSecurityException gse) {
        throw new IOException(gse.toString());
    }
    return bytes;
}
 
public static byte[] encryptMD5(String data) throws IOException {
    return encryptMD5(data.getBytes("UTF-8"));
}

private static byte[] encryptMD5(byte[] bytes) throws IOException {
	MessageDigest md = null;
	try {
		md = MessageDigest.getInstance("MD5");
	} catch (NoSuchAlgorithmException e) {
		throw new IOException(e.toString());
	}
	return md.digest(bytes);
}
 
public static String byte2hex(byte[] bytes) {
    StringBuilder sign = new StringBuilder();
    for (int i = 0; i < bytes.length; i++) {
        String hex = Integer.toHexString(bytes[i] & 0xFF);
        if (hex.length() == 1) {
            sign.append("0");
        }
        sign.append(hex.toUpperCase());
    }
    return sign.toString();
}
                            

Get accesstoken

Interface

Get the token for interface access. Only one request can be accessed in 1 minute. token is the same within the validity period.

Request URL

Method value in common parameters ismethod的值为jimi.oauth.token.get

HTTP request method

GET/POST

Request parameter

(1)common parameter
    See: common parameter

(2)private parameters
    

Name Type Required or not Parameter Description Value description Default value
user_id String Yes User ID
user_pwd_md5 String Yes MD5 of user ID password commons-codec.jar DigestUtils.md5Hex(pwd.getBety()); MD5 result is lowercase
expires_in number Yes access token validity period. Unit:seconds 60-7200

Returned Value

Parameter Type Description
code Int Return code:
0: return correctly
Other: failure. Refer to the error code description
message String If code is not 0, there will be a corresponding error message
result String Result

Result data:

Parameter Type Description
accessToken String accesstoken of following interface, which corresponds to the company account
expiresIn String validity
account String account requested
appKey String APP_KEY distributed by JIMI
refreshToken String Refresh token, which is used for updating accessToken
time String Generated time of Token

Correct return example:

{
  "code": 0,
  "message": "success",
  "result": {
    "appKey": "8FB345B8693CCD003CC2DAB123456789",
    "account": "jimitest",
    "accessToken": "7da3330ec28e3996b6ef4a7123456789",
    "expiresIn": 60,
    "refreshToken": "7da3330ec28e3996b6ef4a7123456789",
    "time": "2017-06-15 10:00:00"
  }
}
                    

Wrong return example:

{"code":xxx,"message":"Incorrect user name or password"}

Refresh accesstoken

Interface

Interface is used to update token compulsorily when accesstoken is about to be invalidated.

Request URL

Method value in the common parameters is jimi.oauth.token.refresh

HTTP Request method

GET/POST

Request parameters

(1)common parameter
    see:common parameter

(2)private parameters
    

Parameter Type Required or not Description Value range Default value
access_token String Yes Accesstoken
refresh_token String Yes Authorized refresh accesstoken
expires_in String Yes access toke validity,unit: second 60-7200

Value returned

Parameter Type Description
code Int Return code:
0: return correctly
Other: failure. Refer to the error code description
message String If code is not 0, there will be a corresponding error message
result String result

Result data:

Parameter Type Description
accessToken String Accesstoken for follow-on interface access, which is corresponded to the company account.
expiresIn String Valid period
account String Requested account
appKey String APP_KEY assigned to the customer by JIMI
refreshToken String Refresh token for updating accessToken
time String Generated time of Token

Correct return example:

{
  "code": 0,
  "message": "success",
  "result": {
    "appKey": "8FB345B8693CCD003CC2DAB123456789",
    "account": "jimitest",
    "accessToken": "7da3330ec28e3996b6ef4a7123456789",
    "expiresIn": 60,
    "refreshToken": "7da3330ec28e3996b6ef4a7123456789",
    "time": "2017-06-15 10:00:00"
  }
}
                    

Wrong return example:

{"code":xxx,"message":"Illegal request,token is invalid"}

Create platform account

Interface

Create sub-account for designated account

Request URL

Method value in the common parameters is jimi.user.child.create

HTTP request method

POST

Request parameters

(1)common parameter
    see:common parameter

(2)private parameters
    

Parameter Type Required or not Description Value range Default value
access_token String Yes accesstoken
top_account String Yes superior account Value range: 3-30 characters
nick_name String Yes client's name Value range: 3-50 characters
account_type String Yes Newly-added account type (8: agents, 9: ordinary users, 11: sales)Description: the following can be created by sales: sales, agents, ordinary users; agents can create: agents, ordinary users; ordinary users can create: ordinary users
account String Yes Login account Value range: 3-30 characters
password String Yes password,value encrypted by md5, lower case Fixed value in 32 bits Use commons-codec.jar
DigestUtils.md5Hex(pwd.getBety());
phone String No phone number Value range: 0-20 characters
email String No email Value range: 0-50 characters
contact String No Contact Value range: 0-50 characters
company_name String No Company Name Value range: 0-50 characters

Returned Value

Parameter Type Description
code Int Return code:
0: return correctly
Other: failure. Refer to the error code description
message String If code is not 0, there will be a corresponding error message
result String Result

Correct return example:

{
  "code": 0,
  "message": "Add successful",
  "result": null
}
                    

Wrong return example:

{"code":12001,"message":"Account existed/Operation failed"}

Acquire all sub-account information

Interface

Query all sub-account information.

Request URL

Method value in common parameters is jimi.user.child.list

HTTP request method

GET/POST

Request parameters

(1)common parameter
    See: common parameter

(2)private parameters
    

Parameter Type Required or not Default value Description
access_token string Yes - accesstoken: used for identifying legal third party
target string Yes - User account inquired ( account or sub-account used for acquiring token)

Returned value

Parameter Type Description
code int Return code:
0: return correctly
Other: failure. Refer to the error code description
message string If code is not 0, there will be a corresponding error message
result string The returned parameters

Result params list:

Parameter Type Description
account string log in account
name string name
type int Account Type 3:end user 8:tier-1 distributor 9:ordinary users 10:ordinary distributor 11:sales
displayFlag Int Available or not (1:Available,0:not available)
address string location
birth string birthday
companyName string Company Name
email string mailbox
phone string contact number
language string Language (zh,en)
sex int Gender 0 male,1 female
enabledFlag int Flag:1 Available, 0not available
remark string Remark

Correct return example:

{
  "code": 0,
  "message": "success",
  "result": [
    {
      "account": "123123",
      "name": "测试",
      "type": 8,
      "displayFlag": 1,
      "address": null,
      "birth": "2017-04-22 00:00:00",
      "companyName": "",
      "email": "",
      "phone": "",
      "language": "zh",
      "sex": 0,
      "enabledFlag": 1,
      "remark": null
    }
  ]
}
                    

Wrong return example:

{"code":xxx,"message":"The account does not exist"}

Acquire all sub-account IMEI information

Interface

Query all sub-account device information

Request URL

Method value in common parameters isjimi.user.device.list

HTTP request method

GET/POST

Request parameters

(1)common parameter
    See: common parameter

(2)private parameters
    

Parameter Type Required or not Default value Description
access_token string Yes accesstoken: used for identifying legal third party
target string Yes User account enquired ( account or sub-account used for acquiring token)

Returned value

Parameter Type Description
code int Return code:
0: return correctly
Other: failure. Refer to the error code description
message string If code is not 0, there will be a corresponding error message
result string The returned data

Result params list:

Parameter Type Description
imei String Device IMEI
deviceName String Device name
mcType String Device model
mcTypeUseScope String Automobile, electromobile, personal, pet, plane, others
sim String Sim card number
expiration String Expire date
activationTime String Activation time
reMark String Remarks
vehicleName String Vehicle name
vehicleIcon String Vehicle icon
vehicleNumber String License plate number
vehicleModels String Brand
carFrame String Frame number
driverName String Driver name
driverPhone String Driver phone number
enabledFlag int Available or not (1:Available,0:not available)
engineNumber String Motor engine number

Correct return example:

{
  "code": 0,
  "message": "success",
  "result": [
    {
      "imei": "868120145233604",
      "deviceName": "868120145233604",
      "mcType": "GT300L",
      "mcTypeUseScope": "personal",
      "sim": "415451",
      "expiration": "2037-04-01 23:59:59",
      "activationTime": "2017-04-01 11:02:20",
      "reMark": "test",
      "vehicleName": null,
      "vehicleIcon": "bus",
      "vehicleNumber": "1CW591",
      "vehicleModels": null,
      "carFrame": "2235",
      "driverName": "driver",
      "driverPhone": "13825036579",
      "enabledFlag": 1,
      "engineNumber": "8565674"
    }
  ]
}
                    

Wrong return example:

{"code":xxx,"message":"Account queried doesn’t exist"}

Obtain latest location information of IMEI based on the account

Interface

Get the latest location information for all devices under an account name

Request URL

Method value in common parameters isjimi.user.device.location.list

HTTP request method

GET/POST

Request parameters

(1)common parameter
    See: common parameter

(2)private parameters
    

Parameter Type Required or not Default value Description
access_token string Yes accesstoken: used for identifying legal third party
target string Yes User account enquired ( account or sub-account used for acquiring token)
map_type string No If you want to display on Baidu map, the returned latitude and longitude of map_type = BAIDU will be calibrated by baidu calibration

If you want to display on google map, the returned latitude and longitude of map_type=GOOGLE will be calibrated by google calibration. If map_type is null, then return origin latitude and longitude

Returned value

Parameter Type Description
code int Return code:
0: return correctly
Other: failure. Refer to the error code description
message string If code is not 0, there will be a corresponding error message The returned data
result string The returned data

result data:

Parameter Type Description
imei string Device IMEI
deviceName string Device name
icon string Vehicle icon
status string Device status 0, offline; 1, online
lat double Longitude (if the device expires, the value is 0)
lng double Latitude (if the device expires, the value is 0)
expireFlag string Expired or not: 1 expired 0 - not expired
activationFlag string Activate or not 1 - Activate 0 - Not active
posType string GPS, LBS, WIFI,BEACON
locDesc string Location information
gpsTime string GPS positioning time
hbTime string Heartbeat time
string string Speed (unit: km / h)
accStatus string ACC 0: OFF 1: ON
electQuantity string Device battery (0-100), some models are not supported
powerValue string External voltage(0-100), some models are not supported

Correct return example:

{
  "code": 0,
  "message": "success",
  "result": [
    {
      "imei": "868120145233604",
      "deviceName": "868120145233604",
      "icon": "bus",
      "status": "0",
      "posType": "GPS",
      "lat": 22.577282,
      "lng": 113.916604,
      "hbTime": "2017-04-26 09:14:50",
      "accStatus": "0",
      "speed": "0",
      "gpsTime": "2017-04-26 09:17:46",
      "activationFlag": "1",
      "expireFlag": "1",
      "electQuantity": "60",
      "locDesc": null,
      "powerValue": null
    }
  ]
}
                    

Wrong return example:

{"code":xxx,"message":"The account does not exist"}

Get the latest location data based on IMEI

Interface

Get the latest location information for a single or multiple devices

Request URL

Method value in common parameters isjimi.device.location.get

HTTP request method

GET/POST

Request parameters

(1)common parameter
    See:common parameter

(2)private parameters
    

Parameter Type Required or not Default value Description
access_token string Yes accesstoken: used for identifying legal third party
imeis string Yes - Device IMEI. Separate imei by comma; POST is recommended if too many devices (maximum 100 IMEI)
map_type string Yes - If you want to display on Baidu map, the returned latitude and longitude of map_type = BAIDU will be calibrated by baidu calibration

If you want to display on google map, the returned latitude and longitude of map_type=GOOGLE will be calibrated by google calibration. If map_type is null, then return origin latitude and longitude

Returned value

Parameter Type Description
code int Return code:
0: return correctly
Other: failure. Refer to the error code description
message string If code is not 0, there will be a corresponding error message
result string The returned data

Result params list:

Parameter Type Description
imei string Device IMEI
device_info string Device name
icon string Vehicle icon
status string Device status 0, offline; 1, online
lat double Longitude (if the device expires, the value is 0)
lng double Latitude (if the device expires, the value is 0)
expireFlag string Whether expired 1- expired 0 - not expired
activationFlag string Activate or not 1 - Activate 0 - Not active
posType string GPS, LBS, WIFI, BEACON
locDesc string Location information
gpsTime string GPS positioning time
hbTime string Heartbeat time
speed string Speed (unit: km / h)
speed string ACC 0: off 1: on
electQuantity string battery(0-100), Some device models are not supported
powerValue string External voltage(0-100), Some device models are not supported

Correct return example:

{
  "code": 0,
  "message": "success",
  "result": [
    {
      "imei": "868120145233604",
      "deviceName": "868120145233604",
      "icon": "bus",
      "status": "0",
      "posType": "GPS",
      "lat": 22.577282,
      "lng": 113.916604,
      "hbTime": "2017-04-26 09:14:50",
      "accStatus": "0",
      "speed": "0",
      "gpsTime": "2017-04-26 09:17:46",
      "activationFlag": "1",
      "expireFlag": "1",
      "electQuantity": "60",
      "locDesc": null,
      "powerValue": null
    }
  ]
}
                    

Wrong return example:

{"code":xxx,"message":"Illegal device"}

Get the track data based on IMEI

Interface

Single device acquire 2 days track data within 3 months.。

Request URL

Method value in common parameters isjimi.device.track.list

HTTP request method

GET/POST

Request parameters

(1)common parameter
    See:common parameter

(2)private parameters
    

Parameter Type Required or not Default value Description
access_token string Yes - accesstoken: used for identifying legal third party
imei string Yes - Device imei( only 1 each time)
begin_time string Yes - Start time Format: yyyy-MM-dd HH:mm:ss
end_time string Yes - End time Format: yyyy-MM-dd HH:mm:ss end_time should be earlier than current time
map_type string No - If you want to display on Baidu map, the returned latitude and longitude of map_type = BAIDU will be calibrated by baidu calibration

If you want to display on google map, the returned latitude and longitude of map_type=GOOGLE will be calibrated by google calibration. If map_type is null, then return origin latitude and longitude

Returned value

Parameter Type Description
code int Return code:
0: return correctly
Other: failure. Refer to the error code description
message string If code is not 0, there will be a corresponding error message
result string The returned data

result data list:

Parameter Type Description
lng double longitude
lat double latitude
gps_time string GPS positioning time. Format yyyy-MM-dd HH: mm: ss
direction string direction
gpsSpeed string GPS speed
posType string 1. GPS, 2. LBS, 3. WIFI

Correct return example:

{
  "code": 0,
  "message": "success",
  "result": [
    {
      "lat": 22.577144898887813,
      "lng": 113.91674845964586,
      "gpsTime": "2017-04-26 00:00:58",
      "direction": 0,
      "gpsSpeed": -1,
      "posType": 3
    },
    {
      "lat": 22.57708,
      "lng": 113.916631,
      "gpsTime": "2017-04-26 00:01:30",
      "direction": 184,
      "gpsSpeed": 0,
      "posType": 1
    }
  ]
}
                    

Wrong return example:

{"code":xxx,"message":"IMEI does not exist{353419031939627}"}
{" code ":xxx,"message":"The device has expired{353419031939627}"}

Bind the user for the device IMEI

Interface

Bind user by IMEI。

Request URL

Method value in common parameters isjimi.open.device.bind

HTTP request method

POST

Request parameters

(1)common parameter
    See:common parameter

(2)private parameters
    

Parameter Type Required or not Default value Description
access_token string Yes accesstoken: used for identifying legal third party
imei string Yes - Device imei
user_id string Yes - Bound user account, which must be terminal account

Returned value

Parameter Type Description
code int Return code:
0: return correctly
Other: failure. Refer to the error code description
message string If code is not 0, there will be a corresponding error message

Correct return example:

{
  "code": 0,
  "message": "Bind user success",
  "result": null
}
                    

Wrong return example:

{"code":xxx,"message":"The device is already bound to another user"}

Unbind users for device IMEI

Interface

Unbind the user by IMEI

Request URL

Method value in common parameters isjimi.open.device.unbind

HTTP request method

POST

Request parameters

(1)common parameter
    See:common parameter

(2)private parameters
    

Parameter Type Required or not Default value Description
access_token string Yes accesstoken: used for identifying legal third party
imei string Yes - Device imei
user_id string Yes - Original bound user account

Returned value

Parameter Type Description
code int Return code:
0: return correctly
Other: failure. Refer to the error code description
message string If code is not 0, there will be a corresponding error message

Correct return example:

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

Wrong return example:

{"code":xxx,"message":"unauthorized user"}

Modify vehicle information by IMEI

Interface

Modify vehicle information by IMEI

Request URL

Method value in common parameters isjimi.open.device.update

HTTP request method

POST

Request parameters

(1)common parameter
    See:common parameter

(2)private parameters
    

Parameter Type Required or not Default value Description
access_token string Yes accesstoken: used for identifying legal third party
imei string Yes - Device IMEI
device_name string No - Device name
vehicle_name string No - Vehicle name
vehicle_icon string No - Vehicle icon
vehicle_number string No - Vehicle plate number
vehicle_models string No - Vehicle brand
driver_name string No - Driver name
driver_phone string No - Driver phone

Returned value

Parameter Type Description
code int Return code:
0: return correctly
Other: failure. Refer to the error code description
message string If code is not 0, there will be a corresponding error message
result String The returned data

Correct return example:

{
  "code": 0,
  "message": "Modify device vehicle information successfully",
  "result": null
}
                    

Wrong return example:

{"code":xxx,"message":"imei doesn’t exists"}

Device transfer

Interface

Transfer the devices to sub-account.。

Request URL

Method value in common parameters is jimi.open.device.move

HTTP request method

POST

Request parameters

(1)common parameter
    see:common parameter

(2)Private parameters
    

Parameter Type Required or not Default value Description
access_token String Yes accesstoken: used for identifying legal third party
src_account String Yes - Original user account
dest_account String Yes - Target user account (must to be the sub-account of original user account)
imeis String Yes - Device imei (max 500) list, separated by comma

Returned Value

Parameter Type Description
code Int Return code:
0: return correctly
Other: failure. Refer to the error code description
message String If code is not 0, there will be a corresponding error message
result String Result

Correct return example:

{
  "code": 0,
  "message": "Device transfer succeed",
  "result": null
}
                    

Wrong return example:

{"code":12002,"message":"Device transfer failed, result code:217"}

Get command list supported by device

Interface

Get command list supported by device

Request URL

Method value in common parameters isjimi.open.instruction.list

HTTP request method

GET/POST

Request parameters

(1)common parameter
    see:common parameter

(2)Private parameters
    

Parameter Type Required or not Default value Description
access_token String Yes accesstoken: used for identifying legal third party
imei String Yes Device imei

Returned Value

Parameter Type Description
code Int Return code:
0: return correctly
Other: failure. Refer to the error code description
message String If code is not 0, there will be a corresponding error message
result String The returned parameters

Resultparams list:

Parameter Type Description
id String Command code
orderName String Command name
orderContent String Command template
orderExplain String Command explanation
orderMsg String prompt
isOffLine String if support offline command 0: no 1: yes

Correct return example:

{
"code": 0,
"message": "success",
"result": [
    {
"id": 81,
"orderName": "SOS setting",
"orderContent": "SOS,A,{0},{1},{2}#",
"orderExplain": "SOSis used for receive alerts and SOSalerts.SOS number shouldhave3-20 numbers.",
"orderMsg": "",
"isOffLine": "1"
    }
	...
  ]
}
                    

Wrong return example:

{"code":xxx,"message":"Illegal device"}

Command sent by designated device

Interface

Get result of sent command

Request URL

Method value in common parameters isjimi.open.instruction.send

HTTP request method

POST

Request parameters

(1)common parameter
    see:common parameter

(2)Private parameters
    

Parameter Type Required or not Default value Description
access_token String Yes accesstoken: used for identifying legal third party
imei String Yes Device imei
inst_param_json String Yes Commandmessage jsoncharacter string

inst_param_json description

Parameter Type Required or not Default value Description
inst_id String Yes Command code
inst_template String Yes Command template
params Array<string> Yes Command paramsstring Array
is_cover boolean No false Whether cover the existed offline command or not
true-cover false-not cover

Returned Value

Parameter Type Description
code Int Return code:
0: return correctly
Other: failure. Refer to the error code description
message String If code is not 0, there will be a corresponding error message
result String The returned parameters

Correct return example:

{
"code": 0,
"message": "command is successfully sent.",
"result": null
}
                    

Wrong return example:

{"code": 12005,"message": "Fail to send command. Result code:226","result": null}

Getresults of command

Interface

Get result of sent command。

Request URL

Method value in common parameters isjimi.open.instruction.result

HTTP request method

GET/POST

Request parameters

(1)common parameter
    see:common parameter

(2)Private parameters
    

Parameter Type Required or not Default value Description
access_token String Yes accesstoken: used for identifying legal third party
imei String Yes Device imei

Returned Value

Parameter Type Description
code Int Return code:
0: return correctly
Other: failure. Refer to the error code description
message String If code is not 0, there will be a corresponding error message
result String The returned parameters

Result params list:

Parameter Type Description
codeId String Command code
code String Command sent
content String Content replied by device
isExecute String command status 0: execution failed, 1: successful execution, 3: to be sent, 4: canceled
sendTime String Time, format:yyyy-MM-dd HH:mm:ss
sender String sender
receiveDevice String Received imei
isOffLine String 0: online 1: offline
idsource String Command description

Correct return example:

{
"code": 0,
"message": "success",
"result": [
    {
"codeId": "99",
"code": "status#",
"content": "Parameter error",
"isExecute": "4",
"sendTime": "2017-06-19 11:46:00",
"sender": "jimitest",
"receiveDevice": "868120111111117",
"isOffLine": "1",
"idsource": "User-defined command"
    }
  ]
}
                    

Wrong return example:

{"code":xxx,"message":"Illegal device"}

Create geo-fence for IMEI

Interface

Create geo-fence for IMEI

Request URL

Method value in common parameters isjimi.open.device.fence.create

HTTP request method

POST

Request parameters

(1)common parameter
    See: common parameter

(2)Private parameters
    

Parameter Type Required or not Default value Description
access_token string Yes accesstoken: used for identifying legal third party
imei string Yes - Device Imei
fence_name string Yes - Geo-fence name
alarm_type string Yes - Alarm type (in / out / in, out)
report_mode string Yes - Alarm reporting mode, 0: GPRS,1:SMS+GPRS
alarm_switch string Yes - Fence alarm switch(ON/OFF)
lng string Yes - Longitude
lat string Yes - latitude
radius string Yes - Fence radius(1~9999;unit: 100 meters)
zoom_level string Yes - Zoom level (3-19)
map_type string Yes - Map (BAIDU / GOOGLE)

Returned value

Parameter Type Description
code int Return code: 0: return correctly Other: failure. Refer to the error code description If code is not 0, there will be a corresponding error message The returned data
message string If code is not 0, there will be a corresponding error message
result string The returned data. Fence serial number returned if succeed.

Correct return example:

{
  "code": 0,
  "message": "Successfully create geo-fence.",
  "result": "5"
}
                    

Wrong return example:

{
  "code": 41003,
  "message": "Device is not online, geo-fence creation failed ",
  "result": null
}
                    

Delete geo-fence for device IMEI

Interface

Delete geo-fence for device IMEI

Request URL

Method value in common parameters isjimi.open.device.fence.delete

HTTP request method

POST

Request parameters

(1)common parameter
    See:common parameter

(2)Private parameters
    

Parameter Type Required or not Default value Description
access_token string Yes accesstoken: used for identifying legal third party
imei string Yes - Device imei
instruct_no string Yes - Geo-fence command serial number

Returned value

Parameter Type Description
code int Return code:
0: return correctly
Other: failure. Refer to the error code description
message string If code is not 0, there will be a corresponding error message
result string The returned data

Correct return example:

{
  "code": 0,
  "message": "delete the geo fence successfully",
  "result": null
}
                    

Wrong return example:

{
  "code": 41003,
  "message": "The device is not online and geo-fence can’t be deleted",
  "result": null
}
                    

Wifi, base station locating analysis interface

Interface

Allocate by total devices under the account (10 times/day/device. All sub-accounts included)

Request URL

Method value in common parameters isjimi.lbs.address.get

HTTP request method

GET/POST

Request parameters

(1)common parameter
    See:common parameter

(2)Private parameters
    

Parameter Type Required or not Default value Description
access_token string Yes accesstoken: used for identifying legal third party
imei number Yes - Device Imei
lbs number No - (wifi/LBS: at least one) LBS inforamtion group (mcc,mnc,lac,cell,rssi), max 7. Each group has five, which should not be null and sorted in order. MCC, China: 460 MNC LAC information, 2312 23222 CELL code: 23222 RSSI Semaphore-70
Wifi string No - (wifi/LBS: at least one) mac1,rssi1| mac2,rssi2 Mac address, no colon in between. Rssi signal strength

Returned value

Parameter Type Description
code int Return code:
0: return correctly
Other: failure. Refer to the error code description
message string If code is not 0, there will be a corresponding error message
result string The returned data

Result params list:

Parameter Type Description
lng string longitude
lat string latitude
accuracy string Accuracy, the greater the value the better

Correct return example:

{
  "code": 0,
  "message": "success",
  "result": {
    "lat": 40.65615416521587,
    "lng": 109.89894039833524,
    "accuracy": 0
  }
}
                    

Wrong return example:

{"code":xxx,"message":"illegal device"}

Message push interface

Interface

Third-party platform provide the url address to receive message while JIMI platform call the url request to send data.

Message service List

Message service Description
jimi.push.device.alarm Alarm data

Content pushed:

Parameter Type Description
msgType String Message type, corresponding to the message service list
data String The content of the message, corresponding to msgType

Alarm push (jimi.push.device.alarm)

Alarms pushed are as follows:

Parameter Type Description
imei string Device imei
deviceName string Device name
alarmType string Alarm type
alarmName string Alarm name
lat string Latitude
lng string Longitude
alarmTime string Alarm time, format (yyyy-MM-dd HH: mm: ss)

E.g:

{
  "msgType": "jimi.push.device.alarm",
  "data": {
    "imei": "868120145233604",
    "deviceName": "868120145233604",
    "alarmType": "2",
    "alarmName": "Power off alarm",
    "lat": 40.65615416521587,
    "lng": 109.89894039833524,
    "alarmTime": "2017-05-08 12:00:00"
  }
}
                    

Appendix: Device alarm type

Parameter Description
1 SOS
2 Power off alarm
3 Vibration alarm
4 Enter the geo- fence (terminal)
5 Leave the geo- fence (terminal)
6 Speed alarm
9 Displacement alarm
10 Into the satellite blind area alarm
11 Out of the satellite blind area alarm
12 Power on alarm
13 GPS first time positioning alarm
14 External battery low alarm
15 External low power protection alarm
16 SIM card change alarm
17 Shutdown alarm
18 Flight mode alarm after external battery is low
19 Tamper alarm
22 Voice alarm
90 Low battery alarmm
128 Rearview mirror vibration alarm
192 Displacement alarm
194 Low backup battery ala
195 Boundary violation alarm
1001 ACC off
1002 ACC on
1003 Offline alarm
1004 Stop alarm
1005 Stay idle alarm
1006 Enter geo-fence
1007 Leave geo-fence
1008 Outside geo-fence for a long time
1009 Inside geo-fence for a long time