开发 物流服务API 开发指南 物流轨迹服务 物流轨迹服务

物流轨迹服务 最后更新时间: 2023年04月23日

产品简介

货运物流轨迹服务是专门针对物流业务的一套轨迹服务能力,主要包括以下三个服务:

  1. 轨迹上传服务
  2. 订单轨迹计算
  3. 车辆轨迹计算

该服务主要支持物流运输轨迹的采集、回传、纠偏、安全判断等能力。通常在实际场景中是“轨迹上传接口”+“车辆轨迹查询”或者“轨迹上传接口”+“订单轨迹查询”来组合使用。

关键字段释义

在此服务中,引入订单ID(Orderid)、车辆ID(vehicleid)的概念,与物流场景相匹配,两个ID都是由开发者来自由定义,以便与自身业务系统挂钩。

其中,订单ID(Orderid)为当车辆正在服务的订单ID,开发者可以根据自身业务情况来定义,如果没有正在服务的订单,该字段可不传;车辆ID(vehicleid)为车辆唯一标识,允许使用中文、数字、字母、英文横线来定义(如"BJ-A888888"),业务若不存在车辆ID,可以使用车牌号或司机ID,需要请务必确保该标识唯一,否则会导致轨迹数据混乱。

场景示例

某物流企业,同时有A、B、C三辆车正在运营,三辆车为三个不同的vehicleid;A车在某天接到5个订单,分别定义为A1、A2、A3、A4、A5 共5个Orderid,以便在后续通过车辆或者轨迹查询时,可以准确查找对应的轨迹信息。

轨迹上传接口

服务地址

URL

http://tsapi.amap.com/v1/logistics/data/vehicle?key=*************

请求方式

POST

特别注意:该接口是物流API服务收费接口,您如果申请试用或者正式应用都请通过工单系统提交商务合作类工单进行沟通。

请求参数

参数名称

类型

是否必填

说明

key

string

合作方的appKey,

在开放平台控制台申请

msgID

string

消息唯一标识,用于重试的幂等性校验,

建议使用UUID策略(不支持汉字文本填入)

time

long

请求接口时的服务端时间,

Unix时间戳,精确到毫秒值

type

string

固定值"vehicles"

coordType

string

上传车辆位置的坐标系:

· gcj02

· wgs84,会转换为gcj02进行存储

不传情况下,默认值为gcj02

data

object

请求的数据体

vehicles

array

车辆信息数组,

最多支持上传10个元素

vehicleID

string

车辆唯一标识,

允许使用中文、数字、字母、英文横线,

如"BJ-A888888"

业务若不存在车辆ID,可以使用车牌号或司机ID

请务必确保该标识唯一,否则会导致轨迹数据混乱

vehicleType

string

1-200:客车相关类型

201-399:货车相关类型

energyType

int

1.汽油/柴油

2.纯电动

3.插电式混动

vehiclePlate

string

支持支持6位传统车牌和7位新能源车牌;例:plate_number:京XXXXXX;

vehicleSize

int

仅货车生效

0: 微型车

1:轻型车

2:中型车

3:重型车

vehicleLength

double

车辆长度, 仅货车生效

单位米,取值[0 – 30]米,会严格按照填写数字进行限行规避,请按照车辆真实信息合理填写。

vehicleHeight

double

车辆高度, 仅货车生效

单位米,取值[0 – 10]米,会严格按照填写数字进行限行规避,请按照车辆真实信息合理填写。

vehicleWidth

double

车辆宽度, 仅货车生效

单位米,取值[0 – 10]米,会严格按照填写数字进行限行规避,请按照车辆真实信息合理填写。 

vehicleWeight

double

车辆总重, 仅货车生效

单位吨,取值[0 – 200]吨,会严格按照填写数字进行限行规避,请按照车辆真实信息合理填写。 总重的含义是核定载重加上车辆自重的总质量。

vehicleLoad

double

车辆载重, 仅货车生效

单位吨,取值[0 – 200]吨,会严格按照填写数字进行限行规避,请按照车辆真实信息合理填写。

vehicleAxle

int

车辆轴数, 仅货车生效

单位个,取值[0 –50]个,会严格按照填写数字进行限行规避,请按照车辆真实信息合理填写。

vehicleLoadSize

double

仅货车生效,车辆装载体积  单位:平方米, 取值[0-300]

vehicleLoadLength

double

仅货车生效, 车辆装载限长  单位:米, 取值[0-100]

vehicleLoadHeight

double

仅货车生效, 车辆装载限高  单位:米, 取值[0-10]

vehicleLoadWidth

double

仅货车生效, 车辆装载限宽  单位:米, 取值[0-10]

state

int

车辆状态:

· 0 - 不可用

· 1 - 空车(可派单)

· 2 - 空车(预约单锁定,不可派单)

· 3 - (服务中)送驾中(不可派单)

· 4 - (服务中)接驾中(不可派单)

· 5 - 到达指定地点, 等待中(不可派单)

locationtype

int

定位类型:

· 0 - 未知

· 1 - GPS

· 2 - WIFI

· 3 - 基站

该值影响「轨迹查询」纠偏效果

location

string

定位坐标,车辆所在位置

经纬度之间用英文逗号分隔,保留小数点后6位,

如"116.397432,39.908599"

accuracy

double

定位精度,标识定位坐标的横向误差

保留小数点后3位

该值影响「轨迹查询」纠偏效果

direction

double

定位方向,标识定位时刻的朝向

顺时针[0,360]范围内取值,0表示正北方向,保留小数点后4位

该值影响「轨迹查询」纠偏效果

speed

double

定位速度,标识定位时刻的瞬时速度

单位 km/h,保留小数点后3位

该值影响「轨迹查询」纠偏效果

height

double

定位高度,标识定位时刻的海拔

单位 m,保留小数点后3位

该值影响「轨迹查询」纠偏效果

naviLocation

string

导航返回定位点信息

roadInfo

string

当前定位所处路段信息

deviceTime

long

设备获取定位信息时的系统时间,Unix时间戳,精确到毫秒值

该值影响「轨迹查询」纠偏效果

timestamp

long

设备获取定位信息时的网络时间,Unix时间错,精确到毫秒值

轨迹查询时,以此时间作为定位点的时间戳,查询时间区间需要此时间一致

建议:

从服务端转发同步,可以使用服务端接收到定位点的服务时间

从客户端直接同步,可以使用定位返回的网络时间

同一个vehicleId下,每个时间戳只能存在一个定位点

该值影响「轨迹查询」使用

orderID

string

当车辆正在服务的订单ID,如果没有正在服务的订单,该字段可不传

拼车场景下,请将车辆信息同步两次,仅订单ID不一致即可

仅支持大写字母、小写字母、数字

该值影响「轨迹查询」使用

订单轨迹计算

服务地址

URL

http://tsapi.amap.com/v1/logistics/track/order?key=**************

请求方式

POST

请求参数

参数名 

类型 

是否必填 

说明 

key 

string 

应用标识,请在开发者后台进行申请 

orderId 

string 

订单ID 

startLocation 

string 

轨迹开始的开始位置,当获取不到时,可以传0,0 

endLocation 

string 

轨迹结束的终点位置,当获取不到时,可以传0,0 

startTime

int

查询开始时间,Unix时间戳(轨迹点的定位时间),需要精准到毫秒 

endTime

int

查询结束时间,Unix时间戳(轨迹点的定位时间),需要精准到毫秒

结束时间不能大于当前时间,且距离开始时间不能超过24小时。不输入时间则为当前时间

若轨迹较多,建议将时间段进行拆分。 

truncateTime 

string 

否 

· 断点时间,轨迹会按照插入的断点,拆分成多段,用于分段计算里程

· 最多允许10个断点,断点之间用西文逗号分隔

· 断点为unix时间戳,毫秒级

· 断点请按照升序排列,断点之间的间隔需要大于10分钟

注:1.当断点在订单对应轨迹时间范围外,则不截断  

2.断点间隔大于10分钟只涉及中间分段,起点到第一个断点,最后一个断点到终点,没有限制 

isPoints 

int 

否 

是否返回轨迹点:

· 1 - 返回

· 0 - 不返回

默认值 0

返回参数

参数名 

类型 

说明 

errcode 

string 

错误码,参照errCode表 

errmsg 

string 

错误描述,参照errCode表 

errdetail 

string 

错误详情 

data 

object

返回轨迹数据 

duration 

long 

整个订单的累计时长 

distance 

long 

整个订单的累计里程 

startTime 

long 

整个订单的开始时间戳,unix时间戳,毫秒 

endTime 

long 

整个订单的结束时间戳,unix时间戳,毫秒 

toll

long

整条轨迹还原后的收费费用

tracks 

array

轨迹数组,如果轨迹被判断中断,且按照行驶速度不可

进行补路时,会返回多段,且两段之间路程不被计算入订单里程 

duration 

long 

该端轨迹的时长 

distance 

long 

该段轨迹的里程 

startTime 

long 

该段轨迹的开始时间戳,unix时间戳,毫秒 

endTime 

long 

该段轨迹的结束时间戳,unix时间戳,毫秒 

roadClass

int

该段轨迹的道路的RoadClass值

formWay

int

该段轨迹的Formway值

speedLimit

double

该路段的路段限速值

speedOverLimit

boolean

相比于当前道路限速值,判断是否超速                                       

stayInfo

array

所有停留信息,可能有多个或为空

startTime

long

该段停留的开始时间戳,unix时间戳,毫秒

endTime

long

该段停留的开始时间戳,unix时间戳,毫秒

stayTime

long

停留总时长,毫秒

center

string

停留位置的中心点,格式:x,y 

points 

array

该段轨迹对应的轨迹点 

location 

string 

定位坐标,格式:x,y 

locatetime 

long 

定位时间,unix时间戳,毫秒值 

车辆轨迹计算

服务地址

URL

http://tsapi.amap.com/v1/logistics/track/vehicle?key=************

请求方式

POST

请求参数

参数名 

类型 

是否必填 

说明 

key 

string 

应用标识,请在开发者后台进行申请 

vehicleId 

string 

车辆ID 

startTime

string

需要查询的轨迹起始时间 ,Unix时间戳(轨迹点的定位时间),需要精准到毫秒 

endTime

string

需要查询的轨迹终止时间 ,Unix时间戳(轨迹点的定位时间),需要精准到毫秒

结束时间不能大于当前时间,且距离开始时间不能超过24小时。不输入时间则为当前时间

若轨迹较多,建议将时间段进行拆分。 

truncateTime 

string 

· 断点时间,轨迹会按照插入的断点,拆分成多段,用于分段计算里程

· 最多允许10个断点,断点之间用西文逗号分隔

· 断点为unix时间戳,毫秒级

· 断点请按照升序排列,断点之间的间隔需要大于10分钟

注:1.当断点在订单对应轨迹时间范围外,则不截断  

2.断点间隔大于10分钟只涉及中间分段,起点到第一个断点,最后一个断点到终点,没有限制 

isPoints 

string

否 

是否返回轨迹点:

· 1 - 返回

· 0 - 不返回

默认值 0

返回参数

参数名 

类型 

说明 

errcode 

string 

错误码,参照errCode表 

errmsg 

string 

错误描述,参照errCode表 

errdetail 

string 

错误详情 

data 

json 

返回轨迹数据 

duration 

long 

整个订单的累计时长 

distance 

long 

整个订单的累计里程 

startTime 

long 

整个订单的开始时间戳,unix时间戳,毫秒 

toll

long

整条轨迹还原后的收费费用,单位:元。

endTime 

long

整个订单的结束时间戳,unix时间戳,毫秒 

tracks 

array

轨迹数组,如果轨迹被判断中断,且按照行驶速度不可

进行补路时,会返回多段,且两段之间路程不被计算入订单里程 

duration 

long 

该端轨迹的时长 

distance 

long 

该段轨迹的里程 

startTime 

long 

该段轨迹的开始时间戳,unix时间戳,毫秒 

endTime 

long 

该段轨迹的结束时间戳,unix时间戳,毫秒 

roadClass

int

该段轨迹的道路的RoadClass值

formWay

int

该段轨迹的Formway值

speedLimit

double

该路段的路段限速值

speedOverLimit

boolean

相比于当前道路限速值,判断是否超速                                       

stayInfo

array

所有停留信息,可能有多个或为空

startTime

long

该段停留的开始时间戳,unix时间戳,毫秒

endTime

long

该段停留的开始时间戳,unix时间戳,毫秒

stayTime

long

停留总时长,毫秒

center

string

停留位置的中心点,格式:x,y 

points 

array

该段轨迹对应的轨迹点 

location 

string 

定位坐标,格式:x,y 

locatetime 

long 

定位时间,unix时间戳,毫秒值 

返回顶部 示例中心 常见问题 智能客服 公众号
二维码