高德地图猎鹰服务调用指南(Java后端)
本文为调用高德地图猎鹰服务的完整流程指南,包含关键接口说明、代码示例及避坑要点。官方文档可能更新,建议以高德猎鹰服务文档为准。
一、准备工作
- 已获取高德地图的
Web服务Key
(需在控制台绑定猎鹰服务
)
二、核心接口调用流程
1. 申请服务ID(sid)
接口地址
GET/POST https://tsapi.amap.com/v1/track/service/add
请求参数
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
key | String | 是 | 高德开发者Key |
name | String | 是 | 服务名称(自定义) |
响应示例
{"errcode": 0,"errmsg": "OK","data": {"sid": 123456 // 记录此sid用于后续接口}
}
2. 创建终端(Terminal)
接口地址
GET/POST https://tsapi.amap.com/v1/track/terminal/add
请求参数
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
key | String | 是 | 高德开发者Key |
sid | Long | 是 | 上一步获取的sid |
name | String | 是 | 终端名称(如设备ID) |
响应示例
{"errcode": 0,"errmsg": "OK","data": {"tid": 789 // 记录此tid用于后续接口}
}
3. 创建轨迹(Trace)
接口地址
GET/POST https://tsapi.amap.com/v1/track/trace/add
请求参数
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
key | String | 是 | 高德开发者Key |
sid | Long | 是 | 服务ID |
tid | Long | 是 | 终端ID |
trname | String | 是 | 轨迹名称(自定义) |
响应示例
{"errcode": 0,"errmsg": "OK","data": {"trid": 1001 // 记录此trid用于上传轨迹点}
}
4. 上传轨迹点(核心)
接口地址
POST https://tsapi.amap.com/v1/track/point/upload
请求参数
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
key | String | 是 | 高德开发者Key |
sid | Long | 是 | 服务ID |
tid | Long | 是 | 终端ID |
trid | Long | 是 | 轨迹ID |
points | String | 是 | JSON数组(格式见下方) |
points格式示例
[{"location": "116.397428,39.90923", // 经纬度字符串"locatetime": 1659436800000 // 毫秒级时间戳},{"location": "116.407428,39.91923","locatetime": 1659436860000}
]
5. 轨迹查询(含历史轨迹)
接口地址
GET/POST https://tsapi.amap.com/v1/track/terminal/search
请求参数
参数 | 类型 | 必填 | 说明 |
---|---|---|---|
key | String | 是 | 高德开发者Key |
sid | Long | 是 | 服务ID |
tid | Long | 是 | 终端ID |
starttime | Long | 是 | 开始时间(秒级时间戳) |
endtime | Long | 是 | 结束时间(秒级时间戳) |
三、Java代码示例(基于OkHttp)
通用请求方法
import okhttp3.*;public class AmapTracker {private static final OkHttpClient client = new OkHttpClient();// 通用请求方法public static String sendRequest(String url, Map<String, String> params) throws IOException {HttpUrl.Builder urlBuilder = HttpUrl.parse(url).newBuilder();params.forEach(urlBuilder::addQueryParameter);Request request = new Request.Builder().url(urlBuilder.build()).build();try (Response response = client.newCall(request).execute()) {return response.body().string();}}// 示例:创建服务public static void createService() throws IOException {Map<String, String> params = new HashMap<>();params.put("key", "your_key");params.put("name", "delivery_tracking");String result = sendRequest("https://tsapi.amap.com/v1/track/service/add", params);System.out.println(result);}
}
四、避坑指南
-
时间戳单位混淆
- 上传轨迹点:毫秒级时间戳(Java用
System.currentTimeMillis()
) - 查询轨迹:秒级时间戳(需注意单位转换)
- 上传轨迹点:毫秒级时间戳(Java用
-
数据持久化建议
CREATE TABLE amap_tracking (id BIGINT PRIMARY KEY,sid BIGINT NOT NULL,tid BIGINT NOT NULL,trid BIGINT NOT NULL,create_time TIMESTAMP );
-
高频调用限制
- 猎鹰服务有QPS限制(详见官方文档)
- 建议使用异步批量上传策略
五、扩展建议
- 轨迹纠偏:使用
https://tsapi.amap.com/v1/track/trace/rectify
- 电子围栏:结合高德地图围栏API实现进出区域监控
- 轨迹可视化:通过
Loca
组件实现轨迹动态展示