当前位置：首页 > article >正文

高德地图猎鹰服务调用指南（Java后端）

article 2025/3/16 18:31:57

本文为调用高德地图猎鹰服务的完整流程指南，包含关键接口说明、代码示例及避坑要点。官方文档可能更新，建议以高德猎鹰服务文档为准。

一、准备工作

已获取高德地图的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()）
- 查询轨迹：秒级时间戳（需注意单位转换）

数据持久化建议

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