Public Convention
Public Convention
html)
Overview
Application
Dealers have their own system and would like to expand relevant GPS function. The customer account of the de
aler 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
Code explanation
0 0 success
Transport protocols
HTTP,
Flowchart of communication program
Communication flow
User API jimi.user.child.list Check all subaccount information under the account
User API jimi.user.device.list Check all device information under the account
User API jimi.user.device.location.l Check the latest location information for all devices under the ac
ist count
Device API jimi.device.location.get Get the latest location data based on IMEI
Device API jimi.open.device.update Modify the vehicle information for the equipment IMEI
LBS-API jimi.lbs.address.get Remove the geo fence for the device IMEI
Protocol details
Call entry
Authentication
User get access_token by appkey and appSecret, which are provided by JIMI platform. Incoming appkey and ac
cess_token needed and request parameters should be signed when call API. JIMI server will authenticate the re
quest parameters.
Common params
API signature
To prevent the API call hacked by hackers, any API calling needs be with a signature,TOP server will authentica
te signature based on request parameters., Illegal signature request will be rejected. Signature algorithms sup
ported by TOP are: MD5 (sign_Method value in common parameters ismd5). The general process of signature i
s as follows:
Sample
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, f
oobar=4. Order sorted is bar=2, foo=1, foo_bar=3, foobar=4
Put all parameter names and values together, the result is bar2foo1foo_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+se
cret);
Byte stream is showed in hexadecimal. For example:hex(“helloworld”.getBytes(“utf-8”)) = “68656C6C6F776F7
26C64”
Algorithm
public static String signTopRequest(Map params, String secret, String signMethod) throws IOExce
// 1:Check whether the parameters have been sorted
String[] keys = params.keySet().toArray(new String[0]);
Arrays.sort(keys);
Get accesstoken
Interface
Obtain accesstoken which is valid within 2 hours.
Request URL
Method value in common parameters is method的值为jimi.oauth.token.get
Request parameter
(1)common parameter
See: common parameter
(2)private parameters
Returned value
{
"code": 0,
"message": "success",
"result": {
"appKey": "8FB345B8693CCD003CC2DAB61EC8791D",
"account": "jimitest",
"accessToken": "7da3330ec28e3996b6ef4a7e3390ba71",
"expiresIn": 60
}
}
Request URL
Method value in common parameters is jimi.user.child.list
GET/POST
Request parameters
(1)common parameter
See: common parameter
(2)private parameters
Returned value
type int Account Type 3:end user 8:tier-1 distributor 9:ordinary users
10:ordinary distributor 11:sales
{
"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
}
]
}
Interface
Query all sub-account device information
Request URL
Method value in common parameters is jimi.user.device.list
GET/POST
Request parameters
(1)common parameter
See: common parameter
(2)private parameters
Returned value
Parameter Type Description
Request URL
Method value in common parameters is jimi.user.device.location.list
GET/POST
Request parameters
(1)common parameter
See: common parameter
(2)private parameters
Returned value
message string If ret is not 0, there will be a corresponding error message The return
ed data
result数据:
electQuantity string Device battery (0-100), some models are not supported
Interface
Get the latest location information for a single or multiple devices
Request URL
Method value in common parameters is jimi.device.location.get
GET/POST
Request parameters
(1)common parameter
See:common parameter
(2)private parameters
Returned value
powerValue string External voltage(0-100), Some device models are not supported
{"code":xxx,"message":"Illegal device"}
Interface
Single device acquire 2 days track data within 3 months.。
Request URL
Method value in common parameters is jimi.device.track.list
GET/POST
Request parameters
(1)common parameter
See:common parameter
(2)private parameters
Returned value
{
"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:
Interface
Bind user by IMEI。
Request URL
HTTP请求方式
POST
Request parameters
(1)common parameter
See:common parameter
(2)private parameters
Required or Default valu
Parameter Type not e Description
Returned value
{
"code": 0,
"message": "Bind user success",
"result": null
}
Interface
Unbind the user by IMEI
Request URL
POST
Request parameters
(1)common parameter
See:common parameter
(2)private parameters
{
"code": 0,
"message": "Unbound success",
"result": null
}
{"code":xxx,"message":"unauthorized user"}
Interface
Modify vehicle information by IMEI
Request URL
Method value in common parameters is jimi.open.device.update
POST
Request parameters
(1)common parameter
See:common parameter
(2)private parameters
{
"code": 0,
"message": "Modify device vehicle information successfully",
"result": null
}
Interface
Allocate by total devices under the account (10 times/day/device. All sub-accounts included)
Request URL
Method value in common parameters is jimi.lbs.address.get
GET/POST
Request parameters
(1)common parameter
See:common parameter
(2)Private parameters
{
"code": 0,
"message": "success",
"result": {
"lat": 40.65615416521587,
"lng": 109.89894039833524,
"accuracy": 0
}
}
Wrong return example:
{"code":xxx,"message":"illegal device"}
Interface
Create geo-fence for IMEI
Request URL
POST
Request parameters
(1)common parameter
See: common parameter
(2)Private parameters
Returned value
code int Return code: 0: return correctly Other: failure. Refer to the error code
description If ret is not 0, there will be a corresponding error message
The returned data
Parameter Type Description
result string The returned data. Fence serial number returned if succeed.
{
"code": 0,
"message": "Successfully create geo-fence.",
"result": "5"
}
{
"code": 41003,
"message": "Device is not online, geo-fence creation failed ",
"result": null
}
Interface
Delete geo-fence for device IMEI
Request URL
Method value in common parameters is jimi.open.device.fence.delete
POST
Request parameters
(1)common parameter
See:common parameter
(2)Private parameters
Returned value
{
"code": 0,
"message": "delete the geo fence successfully",
"result": null
}
{
"code": 41003,
"message": "The device is not online and geo-fence can’t be deleted",
"result": null
}
Interface
Third-party platform provide the url address to receive message while JIMI platform call the url request to send d
ata.
Content pushed:
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"
}
}
Parameter Description
1 SOS
3 Vibration alarm
6 Speed alarm
9 Displacement alarm
12 Power on alarm
17 Shutdown alarm
19 Tamper alarm
22 Voice alarm
1002 ACC on