高德地图猎鹰服务调用指南（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);}
}

---

四、避坑指南

1. 时间戳单位混淆

   • 上传轨迹点：毫秒级时间戳（Java用System.currentTimeMillis()）
   • 查询轨迹：秒级时间戳（需注意单位转换）

2. 数据持久化建议

   CREATE TABLE amap_tracking (id BIGINT PRIMARY KEY,sid BIGINT NOT NULL,tid BIGINT NOT NULL,trid BIGINT NOT NULL,create_time TIMESTAMP
   );
   

3. 高频调用限制

   • 猎鹰服务有QPS限制（详见官方文档）
   • 建议使用异步批量上传策略

---

五、扩展建议

• 轨迹纠偏：使用https://tsapi.amap.com/v1/track/trace/rectify
• 电子围栏：结合高德地图围栏API实现进出区域监控
• 轨迹可视化：通过Loca组件实现轨迹动态展示