Java 调用百度地图 API 实现实时路况检索实战

业务数据类

主响应对象 BdTrafficDTO 继承自公共类，并包含路况详情列表：

package com.yelang.project.meteorology.domain;
import java.io.Serializable;
import java.util.List;
import com.google.gson.annotations.SerializedName;
import lombok.AllArgsConstructor;
import lombok.EqualsAndHashCode;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;
import lombok.ToString;

@NoArgsConstructor
@AllArgsConstructor
@Setter
@Getter
@ToString(callSuper=true)
@EqualsAndHashCode(callSuper=true)
public class BdTrafficDTO extends BdCommonDTO implements Serializable{
    private static final long serialVersionUID = -5247239994807521257L;
    private String description;
    private BdTrafficEvaluation evaluation;
    @SerializedName("road_traffic")
    private List<BdRoadTrafficDetail> roadTraffic;
}

路况整体评价类 BdTrafficEvaluation：

package com.yelang.project.meteorology.domain;
import java.io.Serializable;
import com.google.gson.annotations.SerializedName;
import lombok.AllArgsConstructor;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;
import lombok.ToString;

@NoArgsConstructor
@AllArgsConstructor
@Setter
@Getter
@ToString
public class BdTrafficEvaluation implements Serializable{
    private static final long serialVersionUID = -5992227893340489097L;
    private int status; // 0:未知 1:畅通 2:缓行 3:拥堵 4:严重拥堵
    @SerializedName("status_desc")
    private String statusDesc;
}

路况详情类 BdRoadTrafficDetail：

package com.yelang.project.meteorology.domain;
import java.io.Serializable;
import java.util.List;
import com.google.gson.annotations.SerializedName;
import lombok.AllArgsConstructor;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;
import lombok.ToString;

@NoArgsConstructor
@AllArgsConstructor
@Setter
@Getter
@ToString
public class BdRoadTrafficDetail implements Serializable{
    private static final long serialVersionUID = 3662254110577542026L;
    @SerializedName("road_name")
    private String roadName;
    @SerializedName("congestion_sections")
    private List<BdTrafficCongestionSection> congestionSections;
}

拥堵路段详情类 BdTrafficCongestionSection：

package com.yelang.project.meteorology.domain;
import java.io.Serializable;
import com.google.gson.annotations.SerializedName;
import lombok.AllArgsConstructor;
import lombok.Getter;
import lombok.NoArgsConstructor;
import lombok.Setter;
import lombok.ToString;

@NoArgsConstructor
@AllArgsConstructor
@Setter
@Getter
@ToString
public class BdTrafficCongestionSection implements Serializable {
    private static final long serialVersionUID = 6723821728526157035L;
    @SerializedName("section_desc")
    private String sectionDesc;
    private int status;
    private double speed;
    @SerializedName("congestion_distance")
    private int congestionDistance;
    @SerializedName("congestion_trend")
    private String congestionTrend;
}

UniHttp 集成及调用

使用 UniHttp 简化 HTTP 请求过程。以下展示接口声明与实际调用逻辑。

接口声明

集成检索服务接口的代码如下：

package com.yelang.project.thridinterface;
import com.burukeyou.uniapi.http.annotation.param.QueryPar;
import com.burukeyou.uniapi.http.annotation.request.GetHttpInterface;
import com.burukeyou.uniapi.http.core.response.HttpResponse;
import com.yelang.project.thridinterface.apiprocessor.BaiduHttpApi;

@BaiduHttpApi(snMode = false)
public interface BaiduTrafficService {
    /**
     * 道路路况查询
     */
    @GetHttpInterface(path = "/traffic/v1/road")
    public HttpResponse<String> roadTraffic(@QueryPar("road_name") String roadName, 
                                            @QueryPar("city") String city, 
                                            @QueryPar("ak") String ak);

    /**
     * 周边路况查询
     */
    @GetHttpInterface(path = "/traffic/v1/around")
    public HttpResponse<String> aroundTraffic(@QueryPar("center") String center, 
                                              @QueryPar("radius") int radius, 
                                              @QueryPar("road_grade") int roadGrade, 
                                              @QueryPar("coord_type_input") String coordTypeInput, 
                                              @QueryPar("coord_type_output") String coordTypeOutput, 
                                              @QueryPar("ak") String ak);
}

需要说明的是，如果 AK 校验方式非 SN 模式，创建接口时需指定 snMode = false。

道路路况查询示例

我们先整理几条长沙市的热门道路进行查询：

package com.yelang.project.unihttp;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;
import com.burukeyou.uniapi.http.core.response.HttpResponse;
import com.google.gson.Gson;
import com.yelang.common.utils.StringUtils;
import com.yelang.project.meteorology.domain.BdTrafficDTO;
import com.yelang.project.thridinterface.BaiduTrafficService;

@SpringBootTest
@RunWith(SpringRunner.class)
public class BaiduTrafficServiceCase {
    private static final String BAIDU_DEFAULT_AK = "yourak";
    @Autowired
    private BaiduTrafficService trafficService;
    private static final String DEFAULT_CITY = "长沙市";

    @Test
    public void testRoadTraffic() throws InterruptedException {
        String [] road_array = {"三一大道","南湖路","五一大道","枫林三路","芙蓉中路"};
        Gson gson = new Gson();
        for(String road : road_array) {
            HttpResponse<String> result = trafficService.roadTraffic(road, DEFAULT_CITY, BAIDU_DEFAULT_AK);
            if(StringUtils.isNotEmpty(result.getBodyResult())) {
                BdTrafficDTO trafficDTO = gson.fromJson(result.getBodyResult(), BdTrafficDTO.class);
                System.out.println(trafficDTO);
            }
            Thread.sleep(1500L);
        }
    }
}

运行后控制台将输出各条道路的拥堵状态，位置和拥堵情况基本一致。

周边路况查询示例

针对热门景点，我们通过坐标拾取器并将坐标转为 wgs84 后进行周边道路实况模拟：

package com.yelang.project.unihttp;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;
import org.springframework.test.context.junit4.SpringRunner;
import com.burukeyou.uniapi.http.core.response.HttpResponse;
import com.google.gson.Gson;
import com.yelang.common.utils.StringUtils;
import com.yelang.project.meteorology.domain.BdTrafficDTO;
import com.yelang.project.thridinterface.BaiduTrafficService;

@SpringBootTest
@RunWith(SpringRunner.class)
public class BaiduTrafficServiceCase {
    private static final String BAIDU_DEFAULT_AK = "yourak";
    @Autowired
    private BaiduTrafficService trafficService;
    private static final String DEFAULT_CITY = "长沙市";

    @Test
    public void testAroundTraffic() throws InterruptedException {
        // 橘子洲景区、芙蓉广场地铁站、岳麓山风景区、湖南省博物馆
        String [] centers = {"28.198986,112.95722","28.198243,112.978962","28.196981,112.943391","28.215134,112.986896"};
        Gson gson = new Gson();
        int radius = 100;
        int roadGrade = 0;
        String coordTypeInput = "wgs84";
        String coordTypeOutput = "bd09ll";

        for(String center : centers) {
            HttpResponse<String> result = trafficService.aroundTraffic(center, radius, roadGrade, coordTypeInput, coordTypeOutput, BAIDU_DEFAULT_AK);
            if(StringUtils.isNotEmpty(result.getBodyResult())) {
                BdTrafficDTO trafficDTO = gson.fromJson(result.getBodyResult(), BdTrafficDTO.class);
                System.out.println(trafficDTO);
            }
            Thread.sleep(1500L);
        }
    }
}

分别对以上位置求解 100 米范围的路网路况信息，可以看到周边实时路况列表输出。

常见问题排查

在实际开发中，以下几个坑点值得注意：

1. 道路名称匹配：特别容易碰到的问题就是道路名称。百度地图本身的路网数据中，如果没有要查找的道路（比如长沙市五一路，实际名称是五一大道），就会报错 road_name 错误。建议先在官方平台查询标准名称，或使用地点提示接口补充。

2. 中心点坐标格式：出现 center 参数错误 通常有两种原因：一是坐标中有空格，二是经度纬度顺序颠倒。标准格式必须是 纬度，经度，且中间不能有空格。

3. 坐标类型选择：遇到 coord_type_input 参数错误 时，通常是输入坐标的类型选错。如果是 GPS 坐标，必须选择 wgs84，而不是 gps。另外需注意，返回结果中并没有 wgs84 选项，默认值为 bd09ll。

4. 参数命名差异：在道路周边服务的请求参数中，道路等级的命名是 road_grade。而在部分文档或返回参数中可能存在命名不一致的情况，需以官方最新文档为准。

总结

通过上述步骤，我们完成了基于 Java 的百度地图路况检索功能落地。重点在于正确封装响应对象、规范接口调用参数以及处理好坐标系统差异。希望这些经验能帮助开发者避免常见陷阱，快速构建稳定的交通信息服务模块。