1. Instruction

1.1 Parameter encoding

Parameter encoding is UTF-8 as standard.

Please refer to: http://en.wikipedia.org/wiki/UTF-8

1.2 Time format

Time format is UNIX timestamp.

Please refer to: https://en.wikipedia.org/wiki/Unix_time

1.3 HTTP MIME

application/json; charset=UTF-8

1.4 The response JSON format

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

If code != 0, it means request is error ,please refer to Chapter 3.

Message is the code description, or it’s empty.

2. API List

2.1 Get access token

Purpose

Get access token for the others requests, every api must contain the access token.The access token is valid for 2 hours only, pleaserefresh it frequestly.Whenyou get a new access token, the old one will be invalid automatically.

Request type

GET

Parameters

Parameter Type Required Description
time long true The time when the client sends request
account string true Distributor ' account
signature string true Encrypted signature,the algorithm is:md5(md5(password) + time),md5 use 32 lower-case characters.

URI

/api/authorization

Example

The password=Abc@34590,md5(md5(Abc@34590) + 1556243443) will calculate out the result signature=3844afd2c3bf68f0f3f4aa0a9ee8ee6c

So the request is: http://api.protrack365.com/api/authorization?time=1556243443&account=test&signature=3844afd2c3bf68f0f3f4aa0a9ee8ee6c

Response Description

JSON KEY Value type Description
record Object
access_token string The access token
expires in long access_token expire time in seconds

Response JSON demo

{
    "record": {
        "access_token": "ACCESS_TOKEN",
        "expires_in": 7200,
    },
    "code": 0
}

2.2 Track

Purpose

Get the latest coordinate data for tracking device.

Request type

GET

Parameters

Parameter Type Required Description
access_token string true The accesstoken
imeis string true Target IMEI list, separated by comma, max 100 IMEIs in one request.

URI

/api/track

Example

http://api.protrack365.com/api/track?access_token=ACCESS_TOKEN&imeis=358899051025339,355139000000234

Response description

JSON KEY Value type Description
imei string The imei of the target
servertime long Current server time
gpstime long Gps time
hearttime long Heart time, the last time when the target sent data.
systemtime long The system time when the target sent gps dta.
longitude double Longitude
latitude double latitude
course int course(Noth is 0, clockwise increase ,max 360.)
speed int speed(KM/H)
acctime long ACC status kept time interval in seconds
accstatus int ACC status
1:ACC ON,
0:ACC OFF,
-1:No acc status
doorstatus int Door status
1:Door open,
0:Door closed,
-1:No door status
chargestatus int Charging status
1:Charging,
0:Not in charging,
-1:No such status
oilpowerstatus int Fule status,
1:Fuel supply ok,
0:Fuel supply off,
-1:No such status
defencestatus int Defence status
1:Defence on,
0:Defence off,
-1:No such status
datastatus int 1:Never online,
2:OK,
3:Expired,
4:Offline
battery int The battery
-1:No battery status

Response JSON demo

{
    "record": [
        {
        "imei": "358899051025339",
        "course": 195,
        "systemtime": 1419905754,
        "gpstime": 1419906052,
        "speed": 0,
        "hearttime": 1419906952,
        "servertime": 1420964313,
        "longitude": 113.909813,
        "latitude": 22.583197,
        "acctime": 1400,
        "accstatus": 1,
        "doorstatus": 0,
        "chargestatus": 0,
        "oilpowerstatus": 1,
        "defencestatus": 0,
        "datastatus": 2,
        "battery": 100
        }
    ],
    "code": 0
}

2.3 Playback

Purpose

Get the GPS data of the target in the time period.

Request type

GET

Parameters

Parameter Type Required Description
access_token string true The access token
imei string true Target's IMEI
begintime long true Begin time
endtime long true End time

URI

/api/playback

Example

http://api.protrack365.com/api/playback?access_token=ACCESS_TOKEN&imei=358899051025339&begintime=1406746394&endtime=1407746394

Response description

JSON KEY Value type Description
record String Data is separated by semicolon,the data in each group is:
longitude,latitude,gpstime,speed,course

Response JSON demo

{
"record": "113.97196,22.568616,1406858664,0,228;113.97196,22.56861,1406858684,0,228;113.97196,22.56861,1406858704,0,228;113.97196,22.56861,1406858724,0,228;113.97196,22.56861,1406858724,0,228;113.97196,22.56861,1406858724,0,228;113.97196,22.56861,1406858724,0,228;113.971934,22.568583,1406858780,0,61;113.971925,22.568585,1406858800,0,61",
"code": 0
}

Remark

This api max return 1000 GPS records at one time, when the client get 1000 records, the client has to request next 1000 records, in this request ,the begin time is the last 1000th record’s gpstime, until client get the records less than 1000. When you get the records less than 1000, it means you’ve got all the GPS records.

2.4 Create Geofence

Purpose

Create a circle geofence.

Request type

POST

Parameters

Parameter Type Required Description
access_token string true The access token
imei string true Target's IMEI
efencename string true The name of Geofence
alarmtype int true Alarm type(0:out,1:in,2:in/out)
longitude double true The longitude of the geofence center
latitude double true The latitude of the geofence center
radius int true Geofence radius(100~5000,unit:meter)

URI

/api/geofence/create

Example

http://api.protrack365.com/api/geofence/create?access_token=ACCESS_TOKEN&imei=358899051025339&efencename=home&alarmtype=0&longitude=113.97196&latitude=22.56861&radius=300

Response JSON demo

{"code":0}

How to send a command?

First call the send command api(2.5) to get command id. then call the query command status api(2.6) in loop until the command status is 1(Respond), max try 30 times, and then we consider the command is timeout.

2.5 Send command

Purpose

send a command to device from server.

Request type

POST

Parameters

Parameter Type Required Description
access_token string true The access token
imei string true Target's IMEI
command string true

The command

RELAY,1: Stop Engine

RELAY,0: Restore Engine

URI

/api/command/send

Example

http://api.protrack365.com/api/command/send?access_token=ACCESS_TOKEN&imei=358899051025339&command=RELAY,1

Response description

JSON KEY Value type Description
record Object
commandid string The id to query command response.

Response JSON demo

{
    "record": {
        "commandid": "1B454"
    },
    "code": 0
}

2.6 Query command response

Purpose

query the command response.

Request type

POST

Parameters

Parameter Type Required Description
access_token string true The access token
commandid string true The id returned from send command

URI

/api/command/query

Example

http://api.protrack365.com/api/command/query?access_token=ACCESS_TOKEN&commandid=1B454

Response description

JSON KEY Value type Description
record Object
response string The command response
commandstatus int

Command status

1: has received response from device

0: not receive response from device

Response JSON demo

{
    "record": {
        "response": "Cut off the fuel supply: Success! Speed: 2km/h.",
        "commandstatus": 1
    },
    "code": 0
}

Remark

This api query once every 1 second, up to 30 seconds.

3. Error code

Code Description Remark
10000 System error
10001 Unknown request
10002 Login timeout
10003 Not login yet
10004 Parameter error
10005 Missing required parameter
10006 The parameter is out of range
10007 Permission denied
10009 Request is too frequency
10010 Access token doesn’t exist
10011 Access token is invalid
10012 Access token is out of date
10013 IMEI is not authorized
10014 Request time error
20001 Account or password error
20005 Target doesn't exist.
20017 Device is offline.
20018 Send command fail.
20023 No Data.
20046 Target is expired.
20048 Unsupported command.