中文Overview

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

The API use UTC time in default: format yyyy-MM-dd HH:mm:ss
UTF-8 and JSON is used by default.
Context-Type:default application/json charset=utf-8
The API use UTC time in default: formatyyyy-MM-dd HH:mm:ss
                    

public attributes of returned data

Code explanation

Communication flow

API data flow

API List

Protocol details

Call entry

Call URL of API. All interfaces use this URL.

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

API signature

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 (Constants.SIGN_METHOD_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 (Constants.SIGN_METHOD_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(Constants.CHARSET_UTF8), "HmacMD5");
        Mac mac = Mac.getInstance(secretKey.getAlgorithm());
        mac.init(secretKey);
        bytes = mac.doFinal(data.getBytes(Constants.CHARSET_UTF8));
    } catch (GeneralSecurityException gse) {
        throw new IOException(gse.toString());
    }
    return bytes;
}
 
public static byte[] encryptMD5(String data) throws IOException {
    return encryptMD5(data.getBytes(Constants.CHARSET_UTF8));
}
 
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

Obtain accesstoken which is valid within 2 hours.

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
    

Returned value

Correct return example：

{
  "code": 0,
  "message": "success",
  "result": {
    "appKey": "8FB345B8693CCD003CC2DAB61EC8791D",
    "account": "jimitest",
    "accessToken": "7da3330ec28e3996b6ef4a7e3390ba71",
    "expiresIn": 60
  }
}
                    

Wrong return example：

{"code":xxx,"message":"Incorrect username or password"}

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
    

Returned value

Result params list：

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
    

Returned value

Result params list：

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
    

Returned value

result数据:

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
    }
  ]
}
                    

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
    

Returned value

Result params list：

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
    }
  ]
}
                    

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
    

Returned value

result data list:

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请求方式

POST

Request parameters

(1)common parameter
    See：common parameter

(2)private parameters
    

Returned value

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
    

Returned value

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
    

Returned value

Correct return example：

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

Wrong return example：

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

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
    

Returned value

Result params list：

Correct return example：

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

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
    

Returned value

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
    

Returned value

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
}
                    

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

Content pushed:

Alarm push (jimi.push.device.alarm)

Alarms pushed are as follows：

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