OPEN API

You can get Open API service from your service provider.

←Back

1.1 Parameter encoding

Parameter encoding is UTF-8 as standard.

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

←Back

1.2 Time format

Time format is UNIX timestamp.

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

←Back

1.3 HTTP MIME

application/json; charset=UTF-8

←Back

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.

←Back

2.1 Get access token

Purpose

Get access token for the others requests, each api must contain the access token. The access token is valid for 2 hours, so we don't need refresh it frequently. We suggest refreshing the access token in every 90 minutes. When you request a new access token, the old one will be invalid immediately.

Request type

GET

Parameters

Parameter Type Required Description
time long true The time when the client sends request
account string true 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: https://gps.protrack.kiwi/api.jsp/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
}
←Back

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

https://gps.protrack.kiwi/api.jsp/api/track?access_token={ACCESS_TOKEN}&imeis=358899123456789,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 data.
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 Fuel 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,
5:Block
battery int The battery
-1:No battery status
mileage int mileage(unit:m)
-1:No mileage.
todaymileage long todaymileage(unit:m)
-1:No todaymileage.
externalpower string External Voltage(unit:V)
"":No external voltage.
fuel string The Fuel(unit:L)
"":No fuel.
fueltime long Fuel time,the last time when the target sent fuel data.
0:No fuel.
temperature array The temperature(unit:℃)
When target sent multiple temperatures, example:["30.90","31.70"]
[ ]:No temperature.
temperaturetime long Temperature time,the last time when the target sent temperature data.
0:No temperature.

Response JSON demo

{
    "record": [
        {
        "imei": "358899123456789",
        "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,
        "mileage": 51654
        "todaymileage": 15654
        "externalpower": "12.1"
        "fuel": "2.6"
        "fueltime": 1419906052
        "temperature": ["21.2"]
        "temperaturetime": 1419906052
        }
    ],
    "code": 0
}

More info

To get device's status, you can follow the flow chart below:

track flow

←Back

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

https://gps.protrack.kiwi/api.jsp/api/playback?access_token={ACCESS_TOKEN}&imei=358899123456789&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.

←Back

2.4 Create circle geofence for device

Purpose

This is a shortcut for fast create a circle geofence and bind the device with the geofence.

Note：
  For creating polygon geofence, please refer to 2.21 Create Geofence and 2.25 Modify device geofence settings bind the device with the geofence(s).

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

https://gps.protrack.kiwi/api.jsp/api/geofence/create?access_token={ACCESS_TOKEN}&imei=358899123456789&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.

←Back

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

RESET: Reset device

LOCKDOOR : Lock Door

UNLOCKDOOR : Unlock Door

SET_MILEAGE : Set Mileage
paramData string false

When you choose to set mileage, you must to fill in paramData

example: {"mileage":"30"}

URI

/api/command/send

Example

https://gps.protrack.kiwi/api.jsp/api/command/send?access_token={ACCESS_TOKEN}&imei=358899123456789&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
}
←Back

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

https://gps.protrack.kiwi/api.jsp/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.

←Back

2.7 Get device list

Purpose

Get device list. (Return maximum 500pcs devices for each account.)

Request type

GET

Parameters

Parameter Type Required Description
access_token string true The access token
account string false Account

URI

/api/device/list

Example

https://gps.protrack.kiwi/api.jsp/api/device/list?access_token={ACCESS_TOKEN}&account=demo

Response description

JSON KEY Value type Description
record Object
imei string Target's IMEI
devicename String Device name
devicetype String Device model
platenumber String Licence plate number
onlinetime long Device first online time
platformduetime long Device platform expire time
simcard String SIM card
iccid String ICCID
activatedtime long Device activated time
userduetime long Device user expire time

Response JSON demo

{
    "code": 0,
    "record": [
        {
            "imei": "512345678901234",
            "devicename": "VT05S-01234",
            "devicetype": "VT05S",
            "platenumber": "TheOne",
            "onlinetime": 0,
            "platformduetime": 0,
            "simcard": "7557862586",
            "iccid": "89966415211160402250",
            "activatedtime": 0,
            "userduetime": 0
        },
        {
            "imei": "123456789123456",
            "devicename": "VT05S-23456",
            "devicetype": "VT05S",
            "platenumber": "",
            "onlinetime": 1419905754,
            "platformduetime": 1588603848,
            "simcard": "",
            "iccid": "",
            "activatedtime": 1419805754,
            "userduetime": 1589603848
        }
    ]
}
←Back

2.8 (Deprecated)Get device alarm information

Purpose

Get the device alarm information in the time period.


Note：
  From 2025-02-14 this api is deprecated, please refer to new api 2.17 Get device alarm information

Request type

GET

Parameters

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

URI

/api/alarm/list

Example

https://gps.protrack.kiwi/api.jsp/api/alarm/list?access_token={ACCESS_TOKEN}&imei=358899123456789&begintime=1406746394&endtime=1407746394

Response description

JSON KEY Value type Description
record String Data is separated by semicolon，the data in each group is: alarm type, longitude, latitude, gpstime, system time,speed,course, Geo-fence ID

Response JSON demo

{
    "code": 0,
    "record": "27,113.885888,22.580592,1541575497,1541575507,40,40,0"
}

Note:

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

For Alarm type details,please refer to Chapter 4.1.

←Back

2.9 Block an account

Purpose

Block an account.

Request type

POST

Parameters

Parameter Type Required Description
access_token string true The access token
account string true Account

URI

/api/user/block

Example

https://gps.protrack.kiwi/api.jsp/api/user/block?access_token={ACCESS_TOKEN}&account=demo

Response JSON demo

{
    "code": 0
}
←Back

2.10 Unblock an account

Purpose

Unblock an account.

Request type

POST

Parameters

Parameter Type Required Description
access_token string true The access token
account string true Account

URI

/api/user/unblock

Example

https://gps.protrack.kiwi/api.jsp/api/user/unblock?access_token={ACCESS_TOKEN}&account=demo

Response JSON demo

{
    "code": 0
}
←Back

2.11 Get account information

Purpose

Get the account's brief information.

Request type

GET

Parameters

Parameter Type Required Description
access_token string true The access token
account string true Account

URI

/api/user/info

Example

https://gps.protrack.kiwi/api.jsp/api/user/info?access_token={ACCESS_TOKEN}&account=demo

Response description

JSON KEY Value type Description
record Object
account String Account
username String User name
email String Email address
mobile String Mobile number
telephone String Telephone
contact String Contact
createtime long Create time
roletype int 1 Distributor, 2 End user, 3 Virtual account
blockstatus int 0:block
1:unblock

Response JSON demo

{
    "code": 0,
    "record": {
        "createtime": 1562570435,
        "mobile": "",
        "telephone": "",
        "contact": "",
        "roletype": 1,
        "account": "demo",
        "email": "openapidemo@gmail.com",
        "blockstatus": 1,
        "username": "openapidemo"
     }
}
←Back

2.12 Get device basic information by IMEIs

Purpose

Get the device(s) basic information according to IMEIs. (Maximum 100pcs in one request.)

Request type

GET

Parameters

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

URI

/api/device/detail

Example

https://gps.protrack.kiwi/api.jsp/api/device/detail?access_token={ACCESS_TOKEN}&imeis=358899123456789,355139000000234

Response description

JSON KEY Value type Description
record Object
imei string Target's IMEI
devicename String Device name
devicetype String Device model
platenumber String Licence plate number
onlinetime long Device first online time
platformduetime long Device platform expire time
simcard String SIM card
iccid String ICCID
activatedtime long Device activated time
userduetime long Device user expire time

Response JSON demo

{
    "code": 0,
    "record": [
        {
            "imei": "512345678901234",
            "devicename": "VT05S-01234",
            "devicetype": "VT05S",
            "platenumber": "TheOne",
            "onlinetime": 0,
            "platformduetime": 0,
            "simcard": "7557862586",
            "iccid": "89966415211160402250",
            "activatedtime": 0,
            "userduetime": 0
        },
        {
            "imei": "123456789123456",
            "devicename": "VT05S-23456",
            "devicetype": "VT05S",
            "platenumber": "",
            "onlinetime": 1419905754,
            "platformduetime": 1588603848,
            "simcard": "",
            "iccid": "",
            "activatedtime": 1419805754,
            "userduetime": 1589603848
        }
    ]
}
←Back

2.13 Send message

Purpose

Send message to account.

Request type

POST

Parameters

Parameter Type Required Description
access_token string true The access token
accounts string true Account list, separated by comma, max 200 accounts in one request.
content string true Max. of 300 characters.

URI

/api/message/send

Example

https://gps.protrack.kiwi/api.jsp/api/message/send?access_token={ACCESS_TOKEN}&accounts=test,name&content=Hello

Response JSON demo

{
    "code": 0
}
←Back

2.14 Mileage report

Purpose

Get mileage report of devices in the time period.

Request type

GET

Parameters

Parameter Type Required Description
access_token string true The access token
imeis string true Target IMEI list, separated by comma, max 100 IMEIs in one request.
begintime long true Begin time. The minute of begintime can only be 0 or 30, for example 01:00, 02:30.
endtime long true End time. The minute of endtime can only be 0 or 30, for example 01:00, 02:30.

* The begintime is included ,endtime is not included.
* The maximum interval between begintime and endtime is 7 days.

URI

/api/device/mileage

Example

https://gps.protrack.kiwi/api.jsp/api/device/mileage?access_token={ACCESS_TOKEN}&imeis=351000091413001,351000091413002,351000091413003,351000091413004&begintime=1631721600&endtime=1631808000

Response Description

JSON KEY Value type Description
record Array
imei string Device imei
mileage double mileage of device, in km

Response JSON demo

{
    "record": [
        {
            "imei": "351000091413001",
            "mileage": 338.21
        },
        {
            "imei": "351000091413002",
            "mileage": 500.56
        },
        {
            "imei": "351000091413003",
            "mileage": 280.87
        },
        {
            "imei": "351000091413004",
            "mileage": 621.21
        }
    ],
    "code": 0
}
←Back

2.15 Get sub-customer list

Purpose

Get sub-customer list. (Return maximum 500pcs users.)

Request type

GET

Parameters

Parameter Type Required Description
access_token string true The access token
account string false Account

URI

/api/user/list

Example

https://gps.protrack.kiwi/api.jsp/api/user/list?access_token={ACCESS_TOKEN}&account=demo

Response description

JSON KEY Value type Description
record Object
account String Account
username String User name
email String Email address
mobile String Mobile number
telephone String Telephone
contact String Contact
createtime long Create time
roletype int 1 Distributor, 2 End user, 3 Virtual account
blockstatus int 0:block
1:unblock
hassubcustomer boolean true:Has subcustomer
false:No subcustomer

Response JSON demo

{
"code": 0,
"record": [
        {
           "createtime": 1562570435,
           "mobile": "",
           "telephone": "",
           "contact": "",
           "roletype": 1,
           "account": "demo",
           "email": "openapidemo@gmail.com",
           "blockstatus": 1,
           "username": "openapidemo",
           "hassubcustomer": true
        },
        {
           "createtime": 1562670132,
           "mobile": "",
           "telephone": "",
           "contact": "",
           "roletype": 1,
           "account": "demotest",
           "email": "demotest@gmail.com",
           "blockstatus": 1,
           "username": "demotest name",
           "hassubcustomer": false
        }
    ]
}
←Back

2.16 Modify sub-customer password

Purpose

Modify sub-customer password.

Request type

POST

Parameters

Parameter Type Required Description
access_token string true The access token
account string true Account
password string true the algorithm is:md5(password),md5 use 32 lower-case characters.

URI

/api/user/password/set

Example

If the new password is Abc@34590，then md5(Abc@34590) will calculate out the parameter password=9d591136280b3ec563e3062dbb6f915b

https://gps.protrack.kiwi/api.jsp/api/user/password/set?access_token={ACCESS_TOKEN}&account=monitorcenter&password=9d591136280b3ec563e3062dbb6f915b

Response JSON demo

{
    "code": 0
}
←Back

2.17 Get device alarm information

Purpose

Get the device alarm information in the time period.

Request type

GET

Parameters

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

URI

/api/alarm/list2

Example

https://gps.protrack.kiwi/api.jsp/api/alarm/list2?access_token={ACCESS_TOKEN}&imei=358899123456789&begintime=1406746394&endtime=1407746394

Response description

JSON KEY Value type Description
record Array
alarmtype int alarm type. For details,please refer to Chapter 4.1
longitude double longitude
latitude double latitude
gpstime long Gps time
systemtime long The system time when the target sent alarm data
speed int speed(KM/H)
course int course(Noth is 0, clockwise increase ,max 360.)
geofenceid long Geo-fence ID, when alarmtype is 5(geoFenceInAlarm) or 6(geoFenceOutAlarm),
it has a value, otherwise it is 0.
geofencename String Geo-fence Name,when alarmtype is 5(geoFenceInAlarm) or 6(geoFenceOutAlarm),
it has a value, otherwise it is "".

Response JSON demo

{
    "code": 0,
    "record": [
        {
           "alarmtype": 27,
           "latitude": -23.53665,
           "longitude": -49.246352,
           "gpstime": 1541575497,
           "systemtime": 1541575507,
           "speed": 20,
           "course": 8,
           "geofenceid": 0,
           "geofencename": ""
        },
        {
           "alarmtype": 5,
           "latitude": -23.53668,
           "longitude": -49.246362,
           "gpstime": 1541575598,
           "systemtime": 1541575617,
           "speed": 45,
           "course": 93,
           "geofenceid": 1075558,
           "geofencename": "test-geofence"
        }
    ]
}

Note:

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

←Back

2.18 Get device alarm settings information

Purpose

Get the device alarm settings information.

Request type

GET

Parameters

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

URI

/api/device/alertsettings/get

Example

https://gps.protrack.kiwi/api.jsp/api/device/alertsettings/get?access_token={ACCESS_TOKEN}&imei=358899123456789

Response description

JSON KEY Value type Description
record Array
alarmtype int alarm type. For details,please refer to Chapter 4.2
switch int alarm settings switch. 1:on, 0:off
threshold String alarm settings threshold. For details,please refer to Chapter 4.2

Response JSON demo

{
    "code": 0,
    "record": [
        {
           "alarmtype": 7,
           "switch": 0,
           "threshold": "80"
        },
        {
           "alarmtype": 9,
           "switch": 0,
           "threshold": ""
        },
        {
           "alarmtype": 10,
           "switch": 0,
           "threshold": ""
        },
        {
           "alarmtype": 26,
           "switch": 0,
           "threshold": ""
        },
        {
           "alarmtype": 27,
           "switch": 0,
           "threshold": ""
        },
        {
           "alarmtype": 28,
           "switch": 0,
           "threshold": "25"
        },
        {
           "alarmtype": 29,
           "switch": 0,
           "threshold": "6"
        },
        {
           "alarmtype": 30,
           "switch": 0,
           "threshold": "6"
        },
        {
           "alarmtype": 31,
           "switch": 0,
           "threshold": "12"
        },
        {
           "alarmtype": 32,
           "switch": 0,
           "threshold": "12"
        },
        {
           "alarmtype": 34,
           "switch": 1,
           "threshold": "00:00,08:00"
        },
        {
           "alarmtype": 35,
           "switch": 0,
           "threshold": "0"
        },
        {
           "alarmtype": 36,
           "switch": 0,
           "threshold": "0"
        },
        {
           "alarmtype": 41,
           "switch": 0,
           "threshold": "240"
        },
        {
           "alarmtype": 42,
           "switch": 0,
           "threshold": "180"
        },
        {
           "alarmtype": 43,
           "switch": 0,
           "threshold": "10"
        }
    ]
}
←Back

2.19 Modify device alarm settings

Purpose

Modify device alarm settings.

Request type

POST

Parameters

Query Parameter Type Required Description
access_token string true The access token
imei string true Target IMEI
Body Parameter Type Required Description
alarmtype int true alarm type. For details,please refer to Chapter 4.2
switch int true alarm settings switch. 1:on, 0:off
threshold String true alarm settings threshold.
no threshold alarm settings please set to "",
alarm type needs threshold, please set the threshold value.
For details,please refer to Chapter 4.2

URI

/api/device/alertsettings/set

Example

https://gps.protrack.kiwi/api.jsp/api/device/alertsettings/set?access_token={ACCESS_TOKEN}&imei=358899123456789

body-data(application/json):

[
    {
         "alarmtype": 7,
         "switch": 1,
         "threshold": "80"
    },
    {
         "alarmtype": 9,
         "switch": 1,
         "threshold": ""
    },
    {
         "alarmtype": 34,
         "switch": 0,
         "threshold": "00:00,08:00"
    }
]

Response JSON demo

{
    "code": 0
}
←Back

2.20 Get geofence list

Purpose

Get customer geofence list.

Request type

GET

Parameters

Parameter Type Required Description
access_token string true The access token
account string true Account
pagenumber int true page number,from 1
pagesize int true page size,maximum 100

URI

/api/geofence/list

Example

https://gps.protrack.kiwi/api.jsp/api/geofence/list?access_token={ACCESS_TOKEN}&account=demo&pagenumber=1&pagesize=100

Response description

JSON KEY Value type Description
record Object
id String Geofence id
name String Geofence name
type int Geofence type, 2:circle, 3:polygon
parameter String Geofence parameter
type:2(circle), parameter:longitude,latitude,radius(unit:m)
type:3(polygon), parameter:longitude,latitude;longitude,latitude;..;..
Note:maximum 1000 coordinates for polygon
Latitude and longitude retain 6 decimal places.
speeding int In geofence triggered Speeding alarm value.
0 means not turn on the speeding alarm in the fence
Unit: km/h
usetimes String Alert will only be triggered during the periods after you set up.
"" means all day can be triggered
Format: HH:mm,HH:mm;HH:mm,HH:mm;..
Range: [00:00,23:59]
Example: 01:10,02:20
Example: 00:00,06:00;10:00,12:00

Response JSON demo

{
"code": 0,
"record": [
        {
           "id": "1076078",
           "name": "geofence1",
           "type": 2,
           "parameter": "-77.036871,38.907192,1000",
           "speeding": 0
           "usetimes": ""
        },
        {
           "id": "1076079",
           "name": "geofence2",
           "type": 3,
           "parameter": "105.069202,-3.994672;105.077767,-4.000879;105.074495,-4.010923;105.063909,-4.010923;105.060638,-4.000879",
           "speeding": 85
           "usetimes": "00:00,06:00;10:00,12:00"
        }
    ]
}

Note:

The response results are arranged in reverse order of creation time.

←Back

2.21 Create Geofence

Purpose

Create geofence.

Request type

POST

Parameters

Parameter Type Required Description
access_token string true The access token
account string true Target's account
geofencename string true Geofence name
geofencetype int true Geofence type, 2:circle, 3:polygon
geofenceparameter String true Geofence parameter
type:2(circle), parameter:longitude,latitude,radius(unit:m)
type:3(polygon), parameter:longitude,latitude;longitude,latitude;..;..
Note:maximum 1000 coordinates for polygon
Latitude and longitude retain 6 decimal places.
geofencespeeding String false In geofence triggered Speeding alarm value.
Range: [10,400]
Unit: km/h
geofenceusetimes String false Alert will only be triggered during the periods after you set up.
Format: HH:mm,HH:mm;HH:mm,HH:mm;..
Range: [00:00,23:59]
Example: 01:10,02:20
Example: 00:00,06:00;10:00,12:00

URI

/api/geofence/create2

Example

https://gps.protrack.kiwi/api.jsp/api/geofence/create2?access_token={ACCESS_TOKEN}&account=demo&geofencename=geofence1&geofencetype=2&geofenceparameter=27.914489,-25.991502,1000

https://gps.protrack.kiwi/api.jsp/api/geofence/create2?access_token={ACCESS_TOKEN}&account=demo&geofencename=geofence2&geofencetype=2&geofenceparameter=27.914599,-25.991502,1000&geofencespeeding=80

https://gps.protrack.kiwi/api.jsp/api/geofence/create2?access_token={ACCESS_TOKEN}&account=demo&geofencename=geofence3&geofencetype=2&geofenceparameter=27.914489,-25.991502,1000&geofencespeeding=80&geofenceusetimes=00:00,06:00

https://gps.protrack.kiwi/api.jsp/api/geofence/create2?access_token={ACCESS_TOKEN}&account=demo&geofencename=geofence4&geofencetype=3&geofenceparameter=105.069202,-3.994672;105.077767,-4.000879;105.074495,-4.010923

Response JSON demo

{
    "code":0,
    "record":{
        "id": "1075972"
    }
}
←Back

2.22 Delete Geofence

Purpose

Delete geofence.

Note：
  All binding relationship with this fence will be deleted.

Request type

GET

Parameters

Parameter Type Required Description
access_token string true The access token
id string true Geofence id

URI

/api/geofence/delete

Example

https://gps.protrack.kiwi/api.jsp/api/geofence/delete?access_token={ACCESS_TOKEN}&id=123456

Response JSON demo

{
    "code": 0
}
←Back

2.23 Modify Geofence

Purpose

Modify geofence.

Request type

POST

Parameters

Parameter Type Required Description
access_token string true The access token
id String true Geofence id
geofencename String true Geofence name
geofencetype int true Geofence type, 2:circle, 3:polygon
geofenceparameter String true Geofence parameter
type:2(circle), parameter:longitude,latitude,radius(unit:m)
type:3(polygon), parameter:longitude,latitude;longitude,latitude;..;..
Note:maximum 1000 coordinates for polygon
Latitude and longitude retain 6 decimal places.
geofencespeeding String false In geofence triggered Speeding alarm value.
Range: [10,400]
Unit: km/h
geofenceusetimes String false Alert will only be triggered during the periods after you set up.
Format: HH:mm,HH:mm;HH:mm,HH:mm;..
Example: 01:10,02:20
Example: 00:00,06:00;10:00,12:00

URI

/api/geofence/edit

Example

https://gps.protrack.kiwi/api.jsp/api/geofence/edit?access_token={ACCESS_TOKEN}&id=123456&geofencename=geofence1&geofencetype=2&geofenceparameter=27.914489,-25.991502,1000

https://gps.protrack.kiwi/api.jsp/api/geofence/edit?access_token={ACCESS_TOKEN}&id=123456&geofencename=geofence1&geofencetype=2&geofenceparameter=27.914489,-25.991502,1000&geofencespeeding=80

https://gps.protrack.kiwi/api.jsp/api/geofence/edit?access_token={ACCESS_TOKEN}&id=123456&geofencename=geofence1&geofencetype=3&geofenceparameter=105.069202,-3.994672;105.077767,-4.000879&geofencespeeding=80

https://gps.protrack.kiwi/api.jsp/api/geofence/edit?access_token={ACCESS_TOKEN}&id=123456&geofencename=geofence1&geofencetype=3&geofenceparameter=105.069202,-3.994672;105.077767,-4.000879&geofencespeeding=80&geofenceusetimes=00:00,06:00

Response JSON demo

{
    "code": 0
}
←Back

2.24 Get device geofence list

Purpose

Get device geofence list.

Request type

GET

Parameters

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

URI

/api/device/geofence

Example

https://gps.protrack.kiwi/api.jsp/api/device/geofence?access_token={ACCESS_TOKEN}&imei=358899123456789

Response description

JSON KEY Value type Description
record Object
geofenceid String Geofence id
geofencename String Geofence name
in int Alarm when entering the geofence, 1:on, 0:off.
out int Alarm when leaving the geofence, 1:on, 0:off.
speedingalert int Alarm when speeding in the geofence, 1:on, 0:off.
relaycommand int A Stop Engine command will be automatically sent to the selected device once it leaves the Geo-fence, 1:on, 0:off.
Note: This option need to turn on out geofence alert.

Response JSON demo

{
    "code": 0,
    "record": [
        {
           "geofenceid": "1075642",
           "geofencename": "geofence1",
           "in": 1,
           "out": 1,
           "speedingalert": 0,
           "relaycommand": 0
        },
        {
           "geofenceid": "1075643",
           "geofencename": "geofence2",
           "in": 1,
           "out": 1,
           "speedingalert": 1,
           "relaycommand": 1
        }
    ]
}
←Back

2.25 Modify device geofence settings

Purpose

Modify device geofence settings.

Request type

POST

Parameters

Query Parameter Type Required Description
access_token string true The access token
Body Parameter Type Required Description
imei Array true IMEI list.(Maximum 100pcs in one request.)
geofenceconfig Array true
geofenceid String true Geofence id
in int true Alarm when entering the geofence, 1:on, 0:off.
out int true Alarm when leaving the geofence, 1:on, 0:off.
speedingalert int true Alarm when speeding in the geofence, 1:on, 0:off.
relaycommand int true A Stop Engine command will be automatically sent to the selected device once it leaves the Geo-fence, 1:on, 0:off.
Note: This option need to turn on out geofence alert.

URI

/api/device/geofence/set

Example

https://gps.protrack.kiwi/api.jsp/api/device/geofence/set?access_token={ACCESS_TOKEN}

body-data(application/json):

{
    "imei":["368899123456789","358899123456789"],
    "geofenceconfig": [
        {
             "geofenceid": "1075642",
             "in": 1,
             "out": 1,
             "relaycommand": 1,
             "speedingalert": 1
        },
        {
             "geofenceid": "1075643",
             "in": 1,
             "out": 1,
             "relaycommand": 0,
             "speedingalert": 0
        }
    ]
}

Response JSON demo

{
    "code": 0
}

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
10016 Account is blocked
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.
20089 Device is blocked.

4.1 Alarm type

Alarm type Description Remark
1 sosAlarm
2 lowBatteryAlarm
3 powerDisconnectAlarm
4 vibrationAlarm
5 geoFenceInAlarm
6 geoFenceOutAlarm
7 speedingAlarm
8 carMoveAlarm
9 engineOn
10 engineOff
11 tireTemperatureAlarm
12 tireLeakPressureAlarm
13 tireLowPressureAlarm
14 tireHighPressureAlarm
15 gpsDeadZoneInAlarm
16 gpsDeadZoneOutAlarm
17 obdDtcAlarm
18 disassembleAlarm
19 powerOffAlarm
20 collisionAlarm
21 dropAlarm
22 routeAlarm
23 rapidAccelerationAlarm
24 rapidDecelerationAlarm
25 sharpTurnAlarm
26 dooropenAlarm
27 doorcloseAlarm
28 offlineAlarm
29 engineIdleAlarm
30 parkingAlarm
31 oilLeakAlertAlarm
32 oilTheftAlertAlarm
33 jammingAlarm
34 restrictedDrivingAlarm
35 lowTemperatureAlarm
36 highTemperatureAlarm
37 dumpSwitchOnAlarm
38 dumpSwitchOffAlarm
39 armAlarm
40 rolloverAlarm
41 fatigueDrivingAlarm
42 lackBreakFatigueDrivingAlarm
43 lowOilAlarm
44 lowExternalBatteryAlarm

4.2 Alarm settings

Alarm type Alarm description Threshold
7 speedingAlarm Triggered when speed exceeds the threshold.
Range: [10, 400]
Unit: km/h
9 engineOn No threshold needed,controlled by switch only.
10 engineOff No threshold needed,controlled by switch only.
26 dooropenAlarm No threshold needed,controlled by switch only.
27 doorcloseAlarm No threshold needed,controlled by switch only.
28 offlineAlarm No threshold needed,controlled by switch only.
29 engineIdleAlarm Triggered when engine idle time exceeds the threshold.
Range: [2,120]
Unit: minute
30 parkingAlarm Triggered when parking time exceeds the threshold.
Range: [1,120]
Unit: minute
31 refuelAlertAlarm Triggered when refuel exceeds the threshold.
Range: [1,1000]
Unit: L/minute
32 oilTheftAlertAlarm Triggered when fuel drop rate exceeds the threshold.
Range: [1,1000]
Unit: L/minute
34 restrictedDrivingAlarm Triggered when vehicle drives exceed allowed time range.
Format: HH:mm,HH:mm;HH:mm,HH:mm;..
Range: [00:00,23:59]
Example: 00:00,06:00
Example: 01:00,07:00;12:10,13:20
35 lowTemperatureAlarm Triggered when temperature falls below the threshold.
Range: [-100,100]
Unit: °C
36 highTemperatureAlarm Triggered when temperature exceeds the threshold.
Range: [-100,100]
Unit: °C
41 fatigueDrivingAlarm Triggered when continuous driving time exceeds the threshold.
Range: [60,480]
Unit: minute
42 lackBreakFatigueDrivingAlarm Triggered when rest time is shorter than the threshold.
Range: [30,480]
Unit: minute
43 lowOilAlarm Triggered when fuel level falls below the threshold.
Range: [0,1000]
Unit: L
Copyright © 2025 Protrack GPS Ltd . All rights reserve