TMS三方设备GPS接口文档

gmw e3c363ddc4 1 4 years ago
img 9f5619932f 完善文档 5 years ago
README.md e3c363ddc4 1 4 years ago

README.md

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` | 需要返回的数据的字段名,中间用','隔开,如果不传则返回空,可选的字段名参考返回示例中,例:`fields: "path,address,locateTypes"` |

**返回示例**

- 调用成功示例

```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相同。

订单订阅接口状态

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