Open API for Vehicle Tracking

This documentation is about the open API for the platform Vehicle Tracking Station. Any qualified third party applications or websites may utilize this API to empower business.
This API is based on REST standards, and is compatible with all kinds of programming languages.

• 1 Open API Usage Scenarios
• 2 Usage Workflow
• 3 API Summary
• 3.1 Common Parameters
• 3.2 Parameter Encoding
• 3.3 HTTP MIME Type
• 4 API Listing
• 4.1 [Acquire Accesstoken]
• 4.2 [Monitor]
• 4.3 [Tracking]
• 4.4 [History]
• 4.5 [Reverse Geocoder]
• 4.6 [Acquire Target Info]
• 4.7 [Blacklist Check]
• 5 Error Codes
• 6 Access Limitation
• 6.1 Access Frequency
• 6.2 Expiration of Accesstoken
• 7 Terminology
• 7.1 Variables About Times
• 7.2 Target Status

1.The API is used to extend GPS functionalities of the underlining dealers' own systems.
2.Accounts of dealers' own systems should be mapped to accounts(IMEIs) of our vehicle tracking platform.
3.Dealers' application servers issue API requests to get GPS data.

Dealer provides account and password on the vehicle tracking platform to acquire access token.
Dealer then uses the token on their server to access Open API for needed data.

The following figure shows the data exchange flow:

Name	Type	Required	Desc
access_token	string	yes	An access token, used to indicate weather the invoker is authorized. Reference to 4.1 for acquiring the token. Access_token should only be used within your server side code, otherwise it will not work.
account	string	yes	The account which is the one you used to acquire access token.
format	string	not	default to json(json only so far)
time	number	yes	UNIX timestamp, in seconds. Generally the time when the request is invoked.
callback	string	not	When using JS code to invoke Open API, you may pass this parameter to indicate the API to return jsonp formatted result.

The encoding of request and response is utf-8, all parameters in url should be URIEncoded;
The encoding complies with RFC 1738

JSON
Content-type: text/html; charset=utf-8
JSONP
Content-type: text/javascript; charset=utf-8

Description：
Acquire access token.

URL：
http://api.gpsoo.net/1/auth/access_token?

HTTP Method：
GET/POST

Input Parameters：

Name	Type	Required	Default Value	Desc
account	string	yes	-	Account of Dealers
time	number	yes	-	UNIX timestamp, in seconds
signature	string	yes	-	Encrypted signature; algorithm：md5(md5(password of dealer account) + time)

Url Example：
http://api.gpsoo.net/1/auth/access_token?account=testacc&time=1366786321&signature=e9b39daacc811af7109ef1e11a6583bd

Returns：

Name	Type	Desc
ret	uint	Status code： 0: success others: failed Error Codes
msg	string	If ret is not 0, here is the reason.
access_token	string	For authorization
expires_in	number	Expiration of access token, in seconds

Example for Successful Returns：

{
"ret":0,
"msg":"",
"access_token"：" 13667863217ac80dbbaaf3c74cec21f6d6867bff43",
"expires_in":7200
}

Example for Failed Returns：

{"ret":20001,"msg":"Account or password error"}

Notice：
(1) Access_token should be used within server side code only, otherwise it will not work.
(2) If a return code 10006 is received, it means the access_token has expired and should be reacquired.

Description：
Get the newest GPS data of all targets of a specified account.

URL：
http://api.gpsoo.net/1/account/monitor

HTTP Method：
GET/POST

Input Parameters：
（1）Common Parameters
Refer to：Common Parameters
（2）Specific Parameters

Name	Type	Required	Default Value	Desc
target	string	yes	-	Targets to be monitored
map_type	string	not	-	Setting for the type of latitude and longitude to be returned; The value of map_type may be GOOGLE or BAIDU; If map_type is omitted, then the original latitude and longitude will be returned.

Url Example：
http://api.gpsoo.net/1/account/monitor?access_token=0011045701369822736adb020814946df1ded1c8681d026d5c5&map_type=BAIDU &target=mycar&account=testacc&time=1366786321

Returns：

Name	Type	Desc
ret	uint	Status code 0: Success others: Failed Error Codes
msg	string	If ret is not 0, here is the reason.
imei	string	IMEI number of the target
device_info	uint	Status of the target 0: Online 1: Not enabled 2: Expired 3: Offline
gps_time	number	The time given by satellites when target is positioned; UTC formatted, in seconds. If the target is expired, then gps_time would be 0.
sys_ime	number	The time of our server when receiving GPS data; UTC formatted, in seconds. If the target is expired, then sys_ime would be 0.
heart_time	number	The time of our server when receiving heartbeat packet; UTC formatted, in seconds. If the target is expired, then heart_time would be 0.
server_time	number	The time of our server when receiving the underlining API request; UTC formatted, in seconds. If the target is expired, then server_time would be 0.
lng	number	Longitude; If the target is expired, then lng would be 0.
lat	number	Latitude; If the target is expired, then lat would be 0.
course	number	Course of the target; 0 for North, increases along clockwise, the maximum value is 360 If the target is expired, then course would be 0.
speed	number	Moving speed of the target; Unit: km/h If the target is expired, then speed would be -1; If the target is not enabled, then speed would be -9.
status	string	Status information of ACC .tec If the target is expired, then status would be an empty string.

Example for Successful Returns：

{ 
"ret":0,
"msg":"",
"data"： [{
	"imei": "353419031939627",
	"device_info":0,
	"gps_time": 1318409927,
	"sys_time": 1318409919,
	"heart_time": 1318409919,
	"server_time": 1318428292,
	"lng": 113.91919,
	"lat": 22.54546,
	"course": 100,
	"speed": 80},
	{ 
	"imei": "353419032982170",
	"device_info":0,
	"gps_time": 1318409927,
	"sys_time": 1318409919,
	"heart_time": 1318409919,
	"server_time": 1318428292,
	"lng": 113.91919,
	"lat": 22.54546,
	"course": 100,Specific
	"speed": 80}]
}

Example for Failed Returns：

{"ret":20005,"msg":"You are not authorized to get the data."}

Description：
Get the newest GPS data of a single or a batch targets.

URL：
http://api.gpsoo.net/1/devices/tracking

HTTP Method：
GET/POST

Input Parameters：
（1）Common Parameters
Refer to：Common Parameters
（2）Specific Parameters

Name	Type	Required	Default Value	Desc
imeis	string	yes	-	IMEI numbers of targets, separated by commas; The count limit of IMEIs is 100. You may need to put this parameter into the body of request with POST method if there are too many IMEIs to be send.
map_type	string	not	-	Setting for the type of latitude and longitude to be returned; The value of map_type may be GOOGLE or BAIDU; If map_type is omitted, then the original latitude and longitude will be returned.

Url Example：
http://api.gpsoo.net/1/devices/tracking?access_token=0011045701369822736adb020814946df1ded1c8681d026d5c5&map_type=BAIDU &account=testacc&imeis=353419031939627,353419032982170&time=1366786321

Returns：

Name	Type	Desc
ret	uint	Status code 0: Success others: Failed Error Codes
msg	string	If ret is not 0, here is the reason.
imei	string	IMEI number of the target.
device_info	uint	Status of the target 0: Online 1: Not enabled 2: Expired 3: Offline
gps_time	number	The time given by satellites when target is positioned; UTC formatted, in seconds. If the target is expired, then gps_time would be 0.
sys_ime	number	The time of our server when receiving GPS data; UTC formatted, in seconds. If the target is expired, then sys_ime would be 0.
heart_time	number	The time of our server when receiving heartbeat packet; UTC formatted, in seconds. If the target is expired, then heart_time would be 0.
server_time	number	The time of our server when receiving the underlining API request; UTC formatted, in seconds. If the target is expired, then server_time would be 0.
lng	number	Longitude; If the target is expired, then lng would be 0.
lat	number	Latitude; If the target is expired, then lat would be 0.
course	number	Course of the target; 0 for North, increases along clockwise, the maximum value is 360 If the target is expired, then course would be 0.
speed	number	Moving speed of the target; Unit: km/h If the target is expired, then speed would be -1; If the target is not enabled, then speed would be -9.
status	string	Status information of ACC .tec If the target is expired, then status would be an empty string.

Example for Successful Returns：

{ 
"ret":0,
"msg":"",
"data"： [{
	"imei": "353419031939627",
	"device_info":0,
	"gps_time": 1318409927,
	"sys_time": 1318409919,
	"heart_time": 1318409919,
	"server_time": 1318428292,
	"lng": 113.91919,
	"lat": 22.54546,
	"course": 100,
	"speed": 80"},
	{ 
	"imei": "353419032982170",
	"device_info":0,
	"gps_time": 1318409927,
	"gps_time": 1318409919,
	"heart_time": 1318409919,
	"server_time": 1318428292,
	"lng": 113.91919,
	"lat": 22.54546,
	"course": 100,
	"speed": 80}]
}

Example for Failed Returns：

{"ret":20007,"msg":"IMEI不存在(353419031939627)"}

Description：
Get history GPS data of a target.

URL：
http://api.gpsoo.net/1/devices/history

HTTP Method：
GET

Input Parameters：
（1）Common Parameters
Refer to：Common Parameters
（2）Specific Parameters

Name	Type	Required	Default Value	Desc
imei	string	yes	-	IMEI number of the single target.
map_type	string	not	-	Setting for the type of latitude and longitude to be returned; The value of map_type may be GOOGLE or BAIDU; If map_type is omitted, then the original latitude and longitude will be returned.
begin_time	number	yes	-	Begin time of the GPS data interval; UTC formatted, in seconds.
end_time	number	yes	-	End time of the GPS data interval; UTC formatted, in seconds. Should not bigger than current time.
limit	number	not	1000	Setting for the count of GPS points to be returned during the specified time interval along time line.
time	number	yes	-	UNIX timestamp. Used for acquiring data by a couple of consecutive times. time is the gps time of the last gps point of each data batch. If begin_time and end_time span is large, data should be acquired by a couple of times.

Url Example：
http://api.gpsoo.net/1/devices/history?access_token=0011045701369822736adb020814946df1ded1c8681d026d5c5&map_type=BAIDU &account=testacc&imei=353419031939627&time=1366786321&begin_time=1452754256&end_time=14527547562

Returns：

Name	Type	Desc
ret	uint	Status code 0: Success others: Failed Error Codes
msg	string	If ret is not 0, here is the reason.
gps_time	number	The time given by satellites when target is positioned; UTC formatted, in seconds. If the target is expired, then gps_time would be 0.
lng	number	Longitude; If the target is expired, then lng would be 0.
lat	number	Latitude; If the target is expired, then lat would be 0.
course	number	Course of the target; 0 for North, increases along clockwise, the maximum value is 360 If the target is expired, then course would be 0.
speed	number	Moving speed of the target; Unit: km/h

Example for Successful Returns：

{
"ret":0,
"msg":"",
"data":[{
	"gps_time": 1318409927,
	"lng": 113.91919,
	"lat": 22.54546,
	"course": 200,
	"speed": 80
	},{
	"gps_time": 1318410927,
	"lng": 113.91919,
	"lat": 22.54546,
	"course": 180,
	"speed": 80}]
}

Example for Failed Returns：

{"ret":20007,"msg":"IMEI is not existed{353419031939627}"}
{"ret":20010,"msg":"The target has expired{353419031939627}"}

Notice：
The limit parameter default to 1000, and its max value is also 1000 when specified manually. Don't be confused by the name of the parameter, haha...
So you can get 1000 points per request at most. And what if there are more than 1000 points during the specified time interval?
Of course you should issue requests for a couple of times. You may use gps_time of the last GPS point as the begin_time of a new request. When the count of points returned is less than the specified value of the parameter limit, you get all points then.

Description：
Get address detail via latitude and longitude.

URL：
http://api.gpsoo.net/1/tool/address/

HTTP Method：
GET

Input Parameters：
（1）Common Parameters
Refer to：Common Parameters
（2）Specific Parameters

Name	Type	Required	Default Value	Desc
lng	number	yes	-	longitude
lat	number	yes	-	latitude
lang	string	not	-	Language of address to be returned zh-cn: in Chinese Chinese only for the moment
map_type	string	not	-	Type of latitude and longitude passed to the server; The value of map_type may be GOOGLE or BAIDU; If map_type is omitted, then it default to original latitude and longitude.

Url Example： http://api.gpsoo.net/1/tool/address?lng=114.342155&lat=30.682749&access_token=0011045701369822736adb020814946df1ded1c8681d026d5c5&account=testacc&time=1386655342

Returns：

Name	Type	Desc
ret	uint	Status code 0: Success others: Failed Error Codes
msg	string	If ret is not 0, here is the reason.
address	string	Returned address in detail

Example for Successful Returns：

{
"ret":0,
"msg":"",
"address":"湖北省武汉市堤边路.离新队约78米. "
}

Example for Failed Returns：

{"ret":20002,"msg":"Required parameter missing (lng)"}

Description：
Get target info.

URL：
http://api.gpsoo.net/1/account/devinfo/

HTTP Method：
GET/POST

Input Parameters：
（1）Common Parameters
Refer to：Common Parameters
（2）Specific Parameters

Name	Type	Required	Default Value	Desc
target	string	yes	-	The account to be monitored

Url Example： http://api.gpsoo.net/1/account/devinfo?target=test&account=test&access_token=200071015892101425870161325c151729a416478ac71fe7588b70609800010010014010&time=1386655342

Returns：

Name	Type	Desc
ret	uint	Status code 0: Success others: Failed Error Codes
msg	string	If ret is not 0, here is the reason.
imei	string	IMEI number
name	string	name
number	string	plate number
phone	string	phone number
group_id	uint	group id
group_name	string	group name
dev_type	string	type of the device
in_time	uint	enable time
out_time	uint	expire time
sudu	string	will be -9 if not enabled
efence_support	boolean	if electronic fence is supported
children	array	array of sub dealers
id	string	sub dealer ID
name	string	sub dealer login name, this value may be used as the target parameter of other api url to get sub dealer info.
showname	string	sub dealer name

Example for Successful Returns：

{
    "data": [
       {
            "imei": "684611121300041", 
            "name": "goome-00041", 
            "number": "", 
            "phone": "", 
            "group_id": 0, 
            "group_name": "", 
            "dev_type": "X9", 
            "in_time": 1323705600, 
            "out_time": 1862928000, 
            "sudu": "0", 
            "efence_support": true,
        }
    ], 
    "children"：
     [
                {
                    "id"   : “456789”,
                    "name" : “wangtao888”,
                    "showname" : “wangtao888”
                 },
                 {
                    "id"   : “子客户ID”,
                    "name" : “子客户登录名”,
                    "showname" : “子客户名称”
                 }
     ],
    "ret": 0, 
    "msg": ""
}

Example for Failed Returns：

{"ret":20002,"msg":"Required parameter missing (target)"}

Description：
Check if the one is in blacklist.

URL：
http://api.gpsoo.net/1/tool/blacklist

HTTP Method：
GET/POST

Input Parameters：
（1）Common Parameters
Refer to：Common Parameters
（2）Specific Parameters

Name	Type	Required	Default Value	Desc
cardno	string	not	-	ID card No
drive_cardno	string	not	-	Driver's license number

Url Example： http://api.gpsoo.net/1/tool/blacklist?target=test&account=test&access_token=200071015892101425870161325c151729a416478ac71fe7588b70609800010010014010 &time=1386655342&cardno=42027377373788

Returns：

Name	Type	Desc
ret	uint	Status code 0: Success others: Failed Error Codes
data	bool	true for yes, false for not

Example for Successful Returns：

{
    "data": true, 
    "ret": 0, 
    "msg": "" 
}
When access_type=inner, return format：
{
    "data": true, 
    "success": true,
    "errcode": 0,
    "msg": "" 
}

Example for Failed Returns：

{"ret":20002, "msg":"Required parameter missing"}
When access_type=inner, return format：
{"success":false, "errcode":20002, "msg":"Required parameter missing"}

System Level Error Codes：

Code	Desc
10001	System Error
10002	The API you request does not exist
10003	Request frequence exceeds limitation
10004	access_token not existed
10005	access_token error
10006	access_token has expired, a new one should be acquired

Business Level Error Codes：

Code	Desc
20001	Account or Password Error
20002	Required Parameter missing (%s)
20003	Parameter Value Not Valid
20004	Account does not existed
20005	Not authorized to get the account info
20006	The count of targets under the account (%s) exceeds limitation
20007	IMEI (%s) is not existed
20008	Not authorized to get the target info
20009	Count of targets being requestd exceeds limitation
20010	Target (%s) has expired
20011	Map Type Error
20012	Latitude or Longitude Not Valid

API access frequency should be less than 600times per minute per server.
Please contact us if you need to be authorized with higher access frequency.

The expiration of access_token is in 2 hours.
Please contact us if you need to extend the expiration time.

1. datetime: The time given by satellites when target is positioned; UTC formatted, in seconds.
2. systime: The time of our server when receiving GPS data; UTC formatted, in seconds.
3. heartTime: The time of our server when receiving heartbeat packet; UTC formatted, in seconds.
4. servertime: The time of our server when receiving open API request; UTC formatted, in seconds.

There are 4 statuses of targets: Not Enabled, Static, Moving, Offline.
Statuses can be calculated as follwing:
a:servertime-datetime b:servertime-heart_time c:servertime-sys_time
Not Enabled: Speed is -9, and b is greater than 1500 seconds.
Offline: The smaller one of b and c is bigger than 1500 seconds. (This means there is no heartbeat package received within 25 minutes)
Static: If a is greater than 35 seconds(That is to say the target has not been positioned within 2 consecutive signal periods),
or speed is less than a specified value(Take GT02 Device for example, speed will be less than 10 because of static drift)
Moving: a is less than 35 seconds.