基于Java的高德地图公交路线检索服务集成实践

在智慧城市、智慧出行、本地生活服务飞速发展的当下，地理位置服务（LBS）已经成为绝大多数互联网项目的基础能力。其中，公交路线检索与规划是出行系统、便民服务平台、城市运维系统的核心功能之一。传统自研公交路线规划需要搭建海量的城市公交路网数据、实时站点信息、班次时刻表、路况数据，数据维护成本极高，且更新不及时，很容易出现站点废弃、路线改道、班次停运等数据滞后问题，完全不适合中小型项目快速落地。而高德地图作为国内主流的LBS服务提供商，拥有实时更新的全国公交路网数据、精准的站点定位、完整的换乘策略，其开放的Web服务API可以帮助开发者快速实现公交路线检索、换乘规划、路线详情查询等能力，大幅降低开发成本，缩短项目迭代周期。

在实际项目开发中，很多同学对接第三方地图API时，经常会遇到参数不熟悉、请求格式错误、响应数据解析混乱、接口调用失败等问题。本文结合本人真实项目实战，手把手带大家通过Java集成高德地图公交路线检索API，从原理讲解、参数解析、代码实现到单元测试、成果展示，完整落地整套服务。

2、公交数据可以做什么

高德地图公交检索接口返回的结构化数据，具备极高的业务可塑性，能够支撑多种实际业务场景，绝非简单的"查路线"功能，在实际开发中应用非常广泛：

1. 出行服务场景：为小程序、APP、公众号提供公交出行路线规划、最优换乘方案、步行接驳距离、预计耗时、首末班车时间查询能力，支撑用户出行导航需求。

2. 便民政务系统：城市智慧政务、社区服务平台，展示辖区内公交路网分布、站点覆盖情况，辅助民生服务优化。

3. 同城配送运维：快递、外卖、同城运维系统，结合公交路网规划人员通勤、巡检路线，辅助路径优化与时效预估。

4. 数据统计分析：基于公交路线、站点、班次数据，做城市交通流量分析、路网覆盖率统计，为项目运营和城市规划提供数据支撑。

5. 校园/企业通勤服务：企业、校园通勤系统，检索周边公交站点与路线，为员工、学生提供出行参考。

二、公交路线API简介

1、官网网站介绍

高德地图开放平台是官方提供的免费LBS服务对接平台，为开发者提供地图展示、路径规划、地点检索、公交/地铁查询、路况查询等全套Web服务API，支持Web、移动端、后端服务等多端接入。本次我们使用的是高德地图Web服务-公交路径规划API，属于轻量级HTTP接口，无需引入复杂SDK，后端通过HTTP请求即可调用，适配所有Java后端项目。

官方核心资源地址：

开放平台官网：https://lbs.amap.com/

公交路径规划API文档：公交服务API

前置准备工作：

注册高德开放平台开发者账号；
创建Web服务类型应用，获取Key（必填，接口调用唯一凭证）；
开启Web服务API权限，确保密钥可正常调用接口。

2、请求及响应参数简介

本次集成的公交路线检索接口请求地址：https://restapi.amap.com/v3/bus/linename?parameters

请求方式：GET

parameters 代表的参数包括必填参数和可选参数。所有参数均使用和号字符(&)进行分隔。下面的列表枚举了这些参数及其使用规则。

核心请求参数（必选+常用可选）

|------------|----------|----------------------------------------------------------------------------------------------------------------------------|------|------|
| 名称 | 含义 | 规则说明 | 是否必填 | 缺省值 |
| key | 用户唯一标识 | 用户在高德地图官网申请 Web 服务 API 类型Key | 是 | 无 |
| sig | 签名 | 选择数字签名认证的付费用户必填,数字签名获取和使用方法 | 否 | 无 |
| keywords | 查询关键字 | 只支持一个关键字 | 是 | 无 |
| city | 城市 | 可选值：cityname（中文或中文全拼）、citycode、adcode 默认值："全国" adcode 信息可参考城市编码表获取 | 是 | 无 |
| offset | 每页记录数据 | 规则：大于 100 按默认值默认值：20 | 否 | 20 |
| page | 当前页数 | 规则：最大翻页数 10 默认值：1 | 否 | 1 |
| extensions | 控制返回内容 | 可选： base：返回公交路线基本信息 all：返回基本+详细信息（详细信息包含途径站点，首末班车时间等） | 否 | base |
| output | 返回数据格式类型 | 可选：JSON、XML | 否 | JSON |

核心响应参数

关键字搜索的响应结果的格式由请求参数 output 指定。具体响应参数如下：

|---|------------|------------|---------------------------------------------------------------------------------------------------------|-----------------|
| 名称 || 含义 | 说明 | extensions何值值显示 |
| status || 返回结果状态值 | 值为 0 或 1，0 表示失败；1 表示成功 | base/all |
| info || 返回状态说明 | 访问状态值的说明，如果成功返回"ok"，失败返回错误原因，具体见错误码说明。 | base/all |
| infocode || 返回状态说明 | 返回状态说明,10000 代表正确,详情参阅 info 状态表 | base/all |
| buslines || 公交路线的集合 | | base/all |
| | id | 唯一 id | | base/all |
| | type | 公交类型 | | base/all |
| | name | 线路名称 | | base/all |
| | polyline | 线路的坐标串 | | base/all |
| | citycode | 城市的 adcode | | base/all |
| | start_stop | 始发站 | | base/all |
| | end_stop | 终点站 | | base/all |

以上就是公交路线的请求和响应参数对象信息，以上信息是本文的基础知识，也是高德公交路线的具体操作对象，在后续的开发过程中使用很多。

三、Java快速集成高德地图API

本章节基于纯Java后端实现，不依赖任何前端框架，通过uniapi-http发送GET请求调用交接口，封装通用工具类，并通过Junit完成单元测试，可直接复用至SpringBoot、SSM等所有Java项目。

1、接口定义与代码实现

第一步：引入Maven依赖

需要uniapi-http请求工具、JSON解析工具、单元测试依赖，pom.xml新增如下配置：

XML 复制代码

<dependency>
    <groupId>io.github.burukeyou</groupId>
	<artifactId>uniapi-http</artifactId>
	<version>0.2.3</version>
</dependency>

第二步：封装公交路线检索工具类

统一封装请求地址、密钥、请求方法，对外提供通用检索接口，方便业务层直接调用：

java 复制代码

package com.yelang.project.thridinterface;
import com.burukeyou.uniapi.http.annotation.HttpApi;
import com.burukeyou.uniapi.http.annotation.param.QueryPar;
import com.burukeyou.uniapi.http.annotation.request.GetHttpInterface;
import com.burukeyou.uniapi.http.core.response.HttpResponse;
/**
 * -高德公交线路查询服务API接口
 * @author 夜郎king
 * - API地址：https://lbs.amap.com/api/webservice/guide/api-advanced/bus-inquiry#t6
 *
 */
@HttpApi(url = "https://restapi.amap.com/v3/bus/")
public interface AmapBusLineService {
	/**
	 * - 公交路线关键字查询
	 * 
	 * @param keywords   查询关键字,只支持一个关键字 必填
	 * @param city城市     可选值：cityname（中文或中文全拼）、citycode、adcode 默认值："全国" adcode
	 *                   信息可参考城市编码表获取 必填
	 * @param extensions 控制返回内容 可选：base：返回公交路线基本信息
	 *                   all：返回基本+详细信息（详细信息包含途径站点，首末班车时间等）默认base
	 * @param key        用户在高德地图官网 申请 Web 服务 API 类型Key 必填
	 * @return
	 */
	@GetHttpInterface("/linename")
	public HttpResponse<String> convert(@QueryPar("keywords") String keywords, @QueryPar("city") String city,
			@QueryPar("extensions") String extensions, @QueryPar("key") String key);

}

核心代码说明

统一封装请求地址和密钥，避免硬编码冗余，后续更换密钥只需修改常量即可；

2.发送GET请求，自动关闭流和连接，避免资源泄漏；

统一返回JSON对象，方便后续业务层解析路线、耗时、站点等数据；
增加异常捕获，避免接口请求失败导致主线程崩溃。

2、Junit测试集成

工具类编写完成后，我们通过Junit单元测试验证接口可用性，本次测试场景：查询新晃侗族自治县新晃1路的公交路线。

java 复制代码

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.yelang.project.thridinterface.AmapBusLineService;
@SpringBootTest
@RunWith(SpringRunner.class)
public class AmapBusLineServiceCase {
	private static final String AMAP_CLIENT_AK = "your_key";
	@Autowired
	private AmapBusLineService busLineService;
	/**
	 * - 公交路线搜索
	 * @throws InterruptedException 
	 */
	@Test
	public void searchBusLine() throws InterruptedException {
		String keywords = "新晃1路";
		String city = "431227";//表示新晃侗族自治县
		String extensions = "base";
		HttpResponse<String> result = busLineService.convert(keywords, city, extensions, AMAP_CLIENT_AK);
		System.out.println(result.getBodyResult());
	}
}

测试注意事项：

必须替换为自己的高德Web服务Key，否则接口会鉴权失败；
为了能正常获取数据，建议设置具体的目标城市，需要配置city的值，这里选择使用新晃侗族自治县的行政区划代码：431227。

四、成果展示

1、接口调用结果

运行Junit测试方法，控制台打印完整响应数据，核心成功结果如下（脱敏精简版）：

bash 复制代码

{
"status" :
"1",
"info" :
"OK",
"infocode" :
"10000",
"count" :
"2",
"suggestion" :
{ ... },
"buslines" :
[ ... ]
}

具体展开如下：

结果解析：

status=1、infocode=10000，代表接口调用完全成功；
count=2，说明当前起止点共匹配到2套可行公交换乘方案；

2、高德地图检索效果对照

我们将代码检索的公交线路名称，在高德地图官网手动检索公交路线，检索出的路线数量与代码调用结果完全一致。

由此验证：本次Java集成方案稳定可靠，数据精准，完全可以满足线上项目的业务需求，不存在数据偏差、接口失效等问题。

在实际项目中，我们可以基于返回的transits数组，自定义解析字段，封装为VO返回给前端，实现公交路线列表展示、最优路线推荐、耗时预估等功能。

五、总结

本次实战完整完成了Java后端集成高德地图公交路线检索服务的全流程开发，从理论认知、API文档解析、工具类封装、单元测试到成果验证，实现了零门槛快速落地。

通过本次集成实践，总结几点开发心得，帮大家避坑：

密钥区分环境：高德地图Web服务Key、移动端Key、小程序Key不能混用，后端接口必须使用Web服务密钥，否则直接鉴权失败；
参数格式严格校验：经纬度顺序、小数点位数、城市参数格式，是接口调用成功的关键，90%的报错都是参数格式错误导致；
做好状态判断：业务代码中必须优先判断status状态，再解析数据，避免空指针和数据异常；
工具类通用封装：第三方API一定要统一封装工具类，便于后续维护、参数统一修改、异常统一处理。

该方案通用性极强，可直接复用在SpringBoot项目、微服务项目、后台管理系统中，快速落地公交出行相关业务。后续大家可以基于本文代码，拓展路线筛选、路线排序、站点详情、实时路况等拓展功能。行文仓促，定有不足之处，欢迎各位朋友在评论区批评指正，不胜感激。