README.md 16 KB
TMS三方设备GPS接口文档
目录
接口简介
用于对接三方设备的GPS数据，也可以获取轨迹数据。传参方式如无特殊说明均为application/json格式。不支持将参数写进url中传递。小黑卡用户不需要使用此接口上传轨迹数据。
轨迹数据对接流程
1.获取token
此部分请参考3TMS/CTMS第三方接口文档中的： 接口简介 、 接口说明 以及 获取登陆凭证接口 部分。
2.添加设备
在上传设备信息之前，首先需要将设备添加进系统中，注意，此处的添加不是在TMS系统中添加，而是调用添加设备接口进行添加，这是两个不同的数据表，如果没有添加会提示设备不存在。设备只需添加一次即可。
3.上传设备状态及位置
添加完设备以后可以调用上传设备状态位置数据接口进行数据上传。
4.删除设备
三方设备的上限是500台，超过将无法添加新的设备，必须要删除部分设备才能继续添加。
接口详细信息
添加设备接口
1.简要描述 ：用于添加设备，设备上限为每个账号最多500台。
2.请求URL ：/gps/add_device
3.请求方式 ：POST
4.调用频率限制 ：同一设备号一小时内只能添加一次
5.请求参数 ：
| 参数名 | 必选 | 类型 | 说明 |
| :-: | :-: | :-: | - |
| deviceNumber | 是 | String | 设备号 |
6.返回示例 ：
调用成功示例：
{ "code": 200, "message": null, "data": true }调用失败示例： ```java { "message": "操作太频繁", "status": 500 }
{
"message": "设备浙A34421已存在",
"status": 500
}
### 上传设备状态位置数据接口
**1.简要描述** ：上传设备状态位置数据。
**2.请求URL** ：`/gps/push_gps_data`
**3.请求方式** ：POST
**4.调用频率限制** ：一个账号一小时内只允许调用5000次
**5.请求参数** ：
| **参数名** | **必选** | **类型** | **说明** |
| :-: | :-: | :-: | - |
| `deviceNumber` | `是` | `String` | `设备号` |
| `locateTime` | `是` | `Integer` | `轨迹上报时间，时间戳（单位：秒）` |
| `longitude` | `是` | `Double` | `经度` |
| `latitude` | `是` | `Double` | `纬度` |
| `locateType` | `是` | `Integer` | `轨迹上报类型必填：(0：未知，1：GPS，2：基站定位，4：北斗定位，5：GPS 和北斗定位)` |
| `runStatus` | `是` | `Integer` | `设备运行状态必填（1:行驶，2:停止，3:离线）` |
| `addr` | `是` | `String` | `设备具体定位地址` |
| `province` | `是` | `String` | `定位省份` |
| `city` | `是` | `String` | `定位城市` |
| `roadName` | `是` | `String` | `定位具体街道` |
| `powerRate` | `否` | `Integer` | `设备电量（单位：%）` |
| `humidity` | `否` | `Double` | `设备湿度（单位：度）` |
| `temperature` | `否` | `Double` | `设备温度（单位：度）` |
| `speed` | `否` | `Double` | `设备速度（单位：km／h）` |
| `direction` | `否` | `Double` | `设备运动方向（单位：角度）` |
| `abnormalProfile` | `否` | `String` | `异常点类型：简述` |
| `abnormalInfo` | `否` | `String` | `异常点内容：详细描述` |
| `note1-12` | `否` | `String` | `自定义备注，共12个，用于额外的参数` |
**6.返回示例** ：
- 调用成功示例：
```java
{
"code": 200,
"message": null,
"data": {
"message": "成功",
"success": true
}
}
- 调用失败示例：
java { "code": 200, "message": null, "data": { "message": "设备经纬度不能为空且必须大于0", "success": false } }
移除设备接口
1.简要描述 ：用于移除设备
2.请求URL ：/gps/remove_device
3.请求方式 ：POST
4.请求参数 ：
| 参数名 | 必选 | 类型 | 说明 |
| :-: | :-: | :-: | - |
| deviceNumber | 是 | String | 设备号 |
5.返回示例 ：
调用成功示例：
{ "code": 200, "message": null, "data": true }调用失败示例：
{ "code": 200, "message": null, "data": false }
通过车牌号获取绑定设备的轨迹数据
1.简要描述 ：通过车牌号获取绑定设备的轨迹数据
2.请求URL ：/gps/get_gps_data
3.请求方式 ：POST
4.调用频率限制 ：一个账号一小时内只允许调用10000次
5.请求参数 ：
| 参数名 | 必选 | 类型 | 说明 |
| :-: | :-: | :-: | - |
| carNumber | 是 | String | 车牌号，必填，多个车牌用英文','隔开，最多100个 |
| startTime | 否 | Integer | 开始时间，如果不指定结束时间则查询开始时间到当前时间的数据 |
| endTime | 否 | Integer | 结束时间，如果传了结束时间必须传开始时间 |
注：如果不传时间则只查询最近的一个轨迹点，查询时间范围不能超过1小时
6.返回示例 ：
调用成功示例：
{ "code": 200, "message": null, "data": { "苏B285942": //传参时的车牌号 [ { "device": "浙A34421", //车牌号绑定的设备号 "gpsTime": 1547793092, //定位时间 "lng": 120.114997, //精度 "lat": 30.248416, //纬度 "province": "浙江", //省份 "city": "杭州", //城市名 "location": "地址地址地址地址", //定位地址 "roadName": "地址地址地址地址", //街道名 "locateType": 1, //轨迹上报类型必填：(0：未知，1：GPS，2：基站定位，4：北斗定位，5：GPS 和北斗定位) "speed": 0, //速度 "direction": null, //方向 "address": { "province": "浙江", //省 "city": "杭州", //市 "district": "地址地址地址地址", //区 "detail": "地址地址地址地址" //详细地址 }, "runStatus": 1, //设备运行状态必填（1:行驶，2:停止，3:离线） "created": 1547793212, //轨迹信息创建时间 }, { ......... } ], "浙A98727": [.....] } }调用失败示例： ```java { "message": "查询时间范围不得大于1小时", "status": 500 }
{
"message": "车牌号XXXX未绑定设备",
"status": 500
}
### 获取设备号的轨迹数据
**1.简要描述** ：获取设备号的轨迹数据
**2.请求URL** ：`/gps/get_gps_data_by_device`
**3.请求方式** ：POST
**4.调用频率限制** ：一个账号一小时内只允许调用10000次
**5.请求参数** ：
| **参数名** | **必选** | **类型** | **说明** |
| :-: | :-: | :-: | - |
| `device` | `是` | `String` | `设备号，必填，多个设备用英文','隔开，最多100个` |
| `startTime` | `否` | `Integer` | `开始时间，如果不指定结束时间则查询开始时间到当前时间的数据` |
| `endTime` | `否` | `Integer` | `结束时间，如果传了结束时间必须传开始时间` |
**注：如果不传时间则只查询最近的一个轨迹点，查询时间范围不能超过1小时**
**6.返回示例** ：
- 调用成功示例：
```java
{
"code": 200,
"message": null,
"data": {
"867272034426851": //传参时的设备号
[
{
"device": "867272034426851",//设备号
"gpsTime": 1561081870, //定位时间
"lng": 120.1242792, //精度
"lat": 30.2776902, //纬度
"province": "浙江省", //省份
"city": "杭州市", //城市名
"location": "浙江省 杭州市 西湖区 万塘路 靠近广发银行(文三支行)", //定位地址
"roadName": "浙江省 杭州市 西湖区 万塘路 靠近广发银行(文三支行)", //街道名
"powerRate": 72, //电量
"humidity": null, //湿度
"temperature": null, //温度
"locateType": 2, //轨迹上报类型必填：(0：未知，1：GPS，2：基站定位，4：北斗定位，5：GPS 和北斗定位)
"speed": 0, //速度
"direction": 0, //方向
"address": {
"province": "浙江省", //省
"city": "杭州市", //市
"district": "西湖区", //区
"detail": "浙江省 杭州市 西湖区 万塘路 靠近广发银行(文三支行)" //详细地址
},
"runStatus": 1, //设备运行状态必填（1:行驶，2:停止，3:离线）
"created": 1561081873 //轨迹信息创建时间
},
{
......
}
],
"867212233372371": [.......],
}
}
- 调用失败示例： ```java { "message": "查询时间范围不得大于1小时", "status": 500 }
{
"message": "设备号不能为空",
"status": 500
}
## 获取受理单轨迹数据
**简要描述：** 获取受理单轨迹数据
**请求 URL：** `/gps/get_customer_order_track_points`
**请求方式：** POST
**需要认证：** 是
**请求参数：**
| 参数名 | 必选 | 类型 | 说明 |
|:----:|:---:|:-----:|:-----:|
| `customerOrderNumber` | 是 | `String` | 受理单号 |
| `fields` | 否 | `String` | 需要返回的数据的字段名，中间用','隔开，如果不传则返回空，可选的字段名参考返回示例 |
**返回示例**
- 调用成功示例
```java
{
"code": 200,
"message": null,
"data" : {
"path" : [ [ 120.1242792, 30.2776902 ], ... ], //定位点的经纬度信息
"address" : [ "浙江省 杭州市 西湖区 万塘路 靠近广发银行(文三支行)", ...], //地址，值与path字段对应
"locateTypes" : [ 2, 2, 2, ... ], //定位类型，值与path字段对应，类型：0未定位，1：GPS，2：LBS 基站，3：其他，4：北斗，
//5：GPS+北斗，6：WIFI，7：基站Wifi混合定位， 8：格洛纳斯，32：伽利略
"times" : [ 1557817625, 1557817806, ... ], //定位时间，值与path字段对应
"directions" : [ 0.0, 0.0, 0.0, ... ], //方向，值与path字段对应
"speeds" : [ 0.0, 0.0, 0.0, ... ], //速度，值与path字段对应
"DEVICE_GPS_LOCATETYPE" : 1, //定位类型, 0:gps, 1:gps+基站
"isFinished" : false, //受理单是否已完成
"elapsed" : 865180, //耗时
"estimatedArriveTime" : 1558081837, //预估到达时间，时间戳，单位：秒
"progress" : 0.43, //当前进度，1.0为100%
"mileage" : 3, //已行驶里程
"leftMileage" : 7, //剩余里程
"currentGps" : { //当前定位信息
"device" : "867282033466851",
"gpsTime" : 1558080766, //定位时间
"lng" : 120.1242792,
"lat" : 30.2776902,
"province" : "浙江省",
"city" : "杭州市",
"location" : "浙江省 杭州市 西湖区 万塘路 靠近广发银行(文三支行)",
"roadName" : "浙江省 杭州市 西湖区 万塘路 靠近广发银行(文三支行)",
"powerRate" : 79, //内置电量
"locateType" : 2, //定位类型：0未定位，1：GPS，2：LBS 基站，3：其他，4：北斗，5：GPS+北斗， 6：WIFI，7：基站Wifi混合定位， 8：格洛纳斯，32：伽利略
"speed" : 0.0,
"direction" : 0.0,
"address" : { // 省市区及详细地址
"province" : "浙江省",
"city" : "杭州市",
"district" : "西湖区",
"detail" : "浙江省 杭州市 西湖区 万塘路 靠近广发银行(文三支行)"
},
"accStatus" : null, //Acc状态
"runStatus" : 1 //行驶状态: 9 - 未激活， 1 - 行驶，2 - 停止， 3 - 离线
},
"consignerFence" : { //出发围栏信息
"device" : "867282033466851", //设备号
"fenceName" : "出发围栏", //围栏名字
"fenceType" : 1, //围栏类型，1：圆形
"loc" : { //经纬度
"lng" : 120.10449,
"lat" : 30.284574
},
"radius" : 1000, //围栏半径，单位：米
"alarmType" : null, //警报类型，0:出围栏报警, 1:进围栏报警
"remarks" : null //备注
},
"consigneeFence" : { //到达围栏信息，字段含义同出发围栏
"device" : "867282033466851",
"fenceName" : "到达围栏",
"fenceType" : 1,
"loc" : {
"lng" : 120.141405,
"lat" : 30.319037
},
"radius" : 1000,
"alarmType" : null,
"remarks" : null
},
"consigner" : { //发货人信息
"name" : "西湖区吴彦祖", //姓名
"phone" : "19102150001", //手机号
"address" : { //发货地址信息
"province" : "浙江省", //省
"cityCode" : null, //城市代号
"city" : "杭州", //城市
"district" : "西湖区", //区
"name" : "浙江省杭州市西湖区西湖区行政服务中心", //详细地址
"address" : "浙江省杭州市西湖区西湖区行政服务中心", //详细地址
"lng" : 120.10449, //经度
"lat" : 30.284574 //纬度
}
},
"consignee" : { //收货人信息
"name" : "拱墅区黄晓明",
"phone" : "19102151004",
"address" : { //收货地址信息
"province" : "浙江省",
"cityCode" : null,
"city" : "杭州",
"district" : "拱墅区",
"name" : "浙江省杭州市拱墅区拱墅区政协",
"address" : "浙江省杭州市拱墅区拱墅区政协",
"streetNumber" : null,
"lng" : 120.141405,
"lat" : 30.319037
}
}
}
}
- 调用失败示例
{
"status": 500,
"message": "受理单不存在"
}
其他问题
1.如何在系统中查看上传的轨迹
进入TMS系统-->车队管理-->智能管车，点击列表，在底部进行添加设备
其中，车牌号需要先添加进车队管理-->车辆信息管理中，否则添加的时候会提示车辆不存在，设备ID对应你调用接口时传递的设备号，添加完成之后就完成了车辆与设备的绑定关系。车牌号可以与设备ID相同。
添加完成以后，在列表中点击车牌号则可以查看设备的最后一个定位点，点击设备号可以查看设备的轨迹信息。其余信息在操作的小齿轮中进行查看。