kuaihuoyun_gps

TMS三方设备GPS接口文档

• 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
}

• 调用失败示例：

{
    "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.返回示例 ：

• 调用成功示例：

{
    "code": 200,
    "message": null,
    "data": {
        "message": "成功",
        "success": true
    }
}

• 调用失败示例：

{
    "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.调用频率限制 ：每秒最多5次，同时一小时最大请求量为10000次

5.请求参数 ：

参数名	必选	类型	说明
carNumber	是	String	车牌号，必填，多个车牌用英文','隔开，最多50个，查询多个设备时只返回最近的定位点
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:离线，9:未激活）
                "created": 1547793212, //轨迹信息创建时间
            },
            {
                .........
            }
        ],
        "浙A98727": [.....]
    }
}

• 调用失败示例：

{
    "message": "查询时间范围不得大于1小时",
    "status": 500
}

{
    "message": "车牌号XXXX未绑定设备",
    "status": 500
}

获取设备号的轨迹数据

1.简要描述 ：获取设备号的轨迹数据

2.请求URL ：/gps/get_gps_data_by_device

3.请求方式 ：POST

4.调用频率限制 ：每秒最多5次，同时一小时最大请求量为10000次

5.请求参数 ：

参数名	必选	类型	说明
device	是	String	设备号，必填，多个设备用英文','隔开，最多100个
startTime	否	Integer	开始时间，如果不指定结束时间则查询开始时间到当前时间的数据
endTime	否	Integer	结束时间，如果传了结束时间必须传开始时间

注：如果不传时间则只查询最近的一个轨迹点，查询时间范围不能超过1小时

6.返回示例 ：

• 调用成功示例：

{
    "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": [.......],
    }
}

• 调用失败示例：

{
    "message": "查询时间范围不得大于1小时",
    "status": 500
}

{
    "message": "设备号不能为空",
    "status": 500
}

其他问题

1.如何在系统中查看上传的轨迹

进入TMS系统-->车队管理-->智能管车，点击列表，在底部进行添加设备

其中，车牌号需要先添加进车队管理-->车辆信息管理中，否则添加的时候会提示车辆不存在，设备ID对应你调用接口时传递的设备号，添加完成之后就完成了车辆与设备的绑定关系。车牌号可以与设备ID相同。

添加完成以后，在列表中点击车牌号则可以查看设备的最后一个定位点，点击设备号可以查看设备的轨迹信息。其余信息在操作的小齿轮中进行查看。