基于Java和高德开放平台的WebAPI集成实践-以搜索POI2.0为例
目录
前言
在当今数字化时代，地理信息系统（GIS）和位置服务（LBS）已成为许多应用程序的核心组成部分。无论是导航、物流、社交网络还是电子商务，位置数据的获取和处理都显得尤为重要。高德开放平台作为国内领先的地理信息服务提供商，提供了丰富的WebAPI接口，帮助开发者快速集成地图、导航、搜索等功能。其中，POI（Point of Interest）搜索是许多应用场景中的关键功能，它能够帮助用户快速找到附近的兴趣点，如餐馆、酒店、加油站等。
Java作为一种广泛使用的编程语言，因其跨平台性、稳定性和丰富的生态系统，成为许多企业级应用的首选开发语言。将Java与高德开放平台的WebAPI进行集成，不仅可以充分利用Java的强大功能，还能快速实现复杂的地理信息服务。本文将以搜索POI2.0为例，详细介绍如何在Java项目中集成高德开放平台的WebAPI，并实现高效的POI搜索功能。示例将涵盖从API密钥的获取、HTTP请求的发送、数据的解析到最终结果的展示等完整流程。通过本文的学习，开发者将能够掌握Java与高德开放平台WebAPI集成的基本方法，并能够根据实际需求，灵活应用这些技术解决实际问题。
总之，Java与高德开放平台的WebAPI集成，为开发者提供了强大的工具，帮助他们快速构建高效、稳定的地理信息服务应用。通过本文的实践，开发者将能够更好地理解和使用高德开放平台的API，为未来的项目开发打下坚实的基础。
一、高德搜索API简介
介绍高德开放平台的功能和主要服务，包括地图、定位、导航等API的概述。其次介绍如何在高德平台中申请个人的账号，以及简要介绍对接方法。
1、高德开放平台
在之前的系列博客中，我们介绍了天地图的相关WebAPI，基于天地图的WebAPI我们可以做一些应用。由于一些客观存在的原因，比如天地图的一些POI数据，与百度和高德等平台还是有一定差距，下次可以针对某一个具体的检索场景，对同一个区域进行检索，来对比一下三个平台的数据情况，本文暂且不表。因此为了能有更精准的数据参与分析，这里我们来说说如何从高德平台获取数据。进入到开放平台的首页后可以看到以下界面，这里有很多介绍的文字，大家可以到官网看一下，不再赘述。
点击界面中的产品介绍，进入详细的产品介绍页面，操作界面如下：
这里点击搜索进入到具体的搜索专题介绍页面，地图搜索与产品构建息息相关，基于地理空间的搜索结果，可以灵活、直观地呈现在地图图面上，为用户带来全新价值。目前我们的搜索服务包括：POI搜索、地理/逆地理编码、输入提示、天气及行政区域查询。
2、搜索功能介绍
平台的POI搜索API提供了多种搜索方式，包括关键字搜索、周边搜索、多边形搜索等。
关键字搜索：开发者可通过文本关键字搜索地点信息，文本可以是结构化地址，例如：北京市朝阳区望京阜荣街10号；也可以是 POI 名称，例如：首开广场；周边搜索：开发者可设置圆心和半径，搜索圆形区域内的地点信息；多边形区域搜索：开发者可设置首尾连接的几何点组成多边形区域，搜索坐标对应多边形内的地点信息；ID搜索：开发者可通过已知的地点 ID（POI ID）搜索对应地点信息，建议结合输入提示接口使用。
通过这些API，开发者可以根据用户的需求，灵活地获取所需的POI信息。POI搜索2.0版本在原有功能的基础上，进一步优化了搜索算法，提升了搜索结果的准确性和响应速度。同时，API还支持多种数据格式的返回，如JSON、XML等，方便开发者根据项目需求进行数据解析和处理。
3、部分API介绍
关于开放平台接口的API介绍，官方有详细的说明，这里我们以按关键字搜索为例子，详细介绍它的请求参数以及响应参数信息。
关键字搜索 API 服务地址
URL | 请求方式 |
https://restapi.amap.com/v5/place/text?parameters | GET |
parameters 代表的参数包括必填参数和可选参数。所有参数均使用和号字符(&)进行分隔。下面的列表枚举了这些参数及其使用规则。
请求参数
参数名 | 含义 | 规则说明 | 是否必须 | 缺省值 |
key | 高德Key | 用户在高德地图官网 申请 Web 服务 API 类型Key | 必填 | 无 |
keywords | 地点关键字 | 需要被检索的地点文本信息。 只支持一个关键字 ，文本总长度不可超过80字符 | 必填（keyword 或者 types 二选一必填） | 无 |
types | 指定地点类型 | 地点文本搜索接口支持按照设定的 POI 类型限定地点搜索结果；地点类型与 poi typecode 是同类内容，可以传入多个 poi typecode，相互之间用“|”分隔，内容可以参考 POI 分类码表；地点（POI）列表的排序会按照高德搜索能力进行综合权重排序； | 可选（keyword 或者 types 二选一必填） | 120000（商务住宅） 150000（交通设施服务） |
region | 搜索区划 | 增加指定区域内数据召回权重，如需严格限制召回数据在区域内，请搭配使用 city_limit 参数，可输入 citycode，adcode，cityname；cityname 仅支持城市级别和中文，如“北京市”。 | 可选 | 无，默认全国范围内搜索 |
city_limit | 指定城市数据召回限制 | 可选值：true/false 为 true 时，仅召回 region 对应区域内数据。 | 可选 | false |
show_fields | 返回结果控制 | show_fields 用来筛选 response 结果中可选字段。show_fields 的使用需要遵循如下规则： 1、具体可指定返回的字段类请见下方返回结果说明中的“show_fields”内字段类型； 2、多个字段间采用“,”进行分割； 3、show_fields 未设置时，只返回基础信息类内字段。 | 可选 | 空 |
page_size | 当前分页展示的数据条数 | page_size 的取值1-25 | 可选 | page_size 默认为10 |
page_num | 请求第几分页 | 请求第几分页 | 可选 | page_num 默认为1 |
sig | 数字签名 | 请参考 数字签名获取和使用方法 | 可选 | 无 |
output | 返回结果格式类型 | 默认格式为 json，目前只支持 json 格式； | 可选 | json |
callback | 回调函数 | callback 值是用户定义的函数名称，此参数只在 output 参数设置为 JSON 时有效。 | 可选 | 无 |
返回结果
名称 | 类型 | 说明 | ||
status | string | 本次 API 访问状态，如果成功返回1，如果失败返回0。 | ||
info | string | 访问状态值的说明，如果成功返回"ok"，失败返回错误原因，具体见 错误码说明。 | ||
infocode | string | 返回状态说明,10000代表正确,详情参阅info状态表 | ||
count | string | 单次请求返回的实际 poi 点的个数 | ||
pois | object | 返回的 poi 完整集合 | ||
poi | 单个 poi 内包含的完整返回数据 | |||
name | string | poi 名称 | ||
id | string | poi 唯一标识 | ||
location | string | poi 经纬度 | ||
type | string | poi 所属类型 | ||
typecode | string | poi 分类编码 | ||
pname | string | poi 所属省份 | ||
cityname | string | poi 所属城市 | ||
adname | string | poi 所属区县 | ||
address | string | poi 详细地址 | ||
pcode | string | poi 所属省份编码 | ||
adcode | string | poi 所属区域编码 | ||
citycode | string | poi 所属城市编码 | ||
注意以下字段如需返回需要通过“show_fields”进行参数类设置。 | ||||
children | object | 设置后返回子 POI 信息 | ||
id | string | 子 poi 唯一标识 | ||
name | string | 子 poi 名称 | ||
location | string | 子 poi 经纬度 | ||
address | string | 子 poi 详细地址 | ||
subtype | string | 子 poi 所属类型 | ||
typecode | string | 子 poi 分类编码 | ||
sname | string | 子 poi 分类信息 | ||
subtype | string | 再次确认子 poi 分类信息 | ||
business | object | 设置后返回 poi 商业信息 | ||
business_area | string | poi 所属商圈 | ||
opentime_today | string | poi 今日营业时间，如 08:30-17:30 08:30-09:00 12:00-13:30 09:00-13:00 | ||
opentime_week | string | poi 营业时间描述，如 周一至周五:08:30-17:30(延时服务时间:08:30-09:00；12:00-13:30)；周六延时服务时间:09:00-13:00(法定节假日除外) | ||
tel | string | poi 的联系电话 | ||
tag | string | poi 特色内容，目前仅在美食poi下返回 | ||
rating | string | poi 评分，目前仅在餐饮、酒店、景点、影院类 POI 下返回 | ||
cost | string | poi 人均消费，目前仅在餐饮、酒店、景点、影院类 POI 下返回 | ||
parking_type | string | 停车场类型（地下、地面、路边），目前仅在停车场类 POI 下返回 | ||
alias | string | poi 的别名，无别名时不返回 | ||
keytag | string | poi 标识，用于确认poi信息类型 | ||
rectag | string | 用于再次确认信息类型 | ||
indoor | object | 设置后返回室内相关信息 | ||
indoor_map | string | 是否有室内地图标志，1为有，0为没有 | ||
cpid | string | 如果当前 POI 为建筑物类 POI，则 cpid 为自身 POI ID；如果当前 POI 为商铺类 POI，则 cpid 为其所在建筑物的 POI ID。 indoor_map 为0时不返回 | ||
floor | string | 楼层索引，一般会用数字表示，例如8；indoor_map 为0时不返回 | ||
truefloor | string | 所在楼层，一般会带有字母，例如F8；indoor_map 为0时不返回 | ||
navi | object | 设置后返回导航位置相关信息 | ||
navi_poiid | string | poi 对应的导航引导点坐标。大型面状 POI 的导航引导点，一般为各类出入口，方便结合导航、路线规划等服务使用 | ||
entr_location | string | poi 的入口经纬度坐标 | ||
exit_location | string | poi 的出口经纬度坐标 | ||
gridcode | string | poi 的地理格 id | ||
photos | object | 设置后返回 poi 图片相关信息 | ||
title | string | poi 的图片介绍 | ||
url | string | poi 图片的下载链接 | ||
二、Uniapi集成高德API
本节详细介绍如何在Java中使用Uniapi来集成高德api实现相关的检索服务。主要从以下三个部分进行介绍，第一是介绍API的集成流程；第二是介绍如何在Uniapi中定义接口；第三是介绍如何在业务中进行集成。
1、API集成流程
在Java项目中集成高德开放平台的WebAPI，通常需要以下几个步骤：首先，开发者需要在高德开放平台注册账号，并创建应用以获取API密钥（Key）。API密钥是调用高德API的凭证，每个应用都有唯一的密钥。其次，开发者需要在Java项目中引入HTTP客户端库，用于发送HTTP请求并接收API的响应。常用的HTTP客户端库包括Apache HttpClient、OkHttp、Uniapi等，本文将以Uniapi为例重点介绍。接下来，开发者需要根据高德API的文档，构建符合要求的请求URL，并处理API返回的数据。最后，开发者可以根据业务需求，对获取的POI数据进行进一步的处理和展示。关于如何在高德开放平台中申请账号并获取APIkey,大家可以在官方文档中查找，不再做详细的介绍。
2、访问接口的定义
这里介绍如何在Uniapi中创建访问api，用来跟开放平台进行交互，uniapi的操作比较简单，下面是示例代码：
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; @HttpApi(url = "https://restapi.amap.com/v5") public interface AmapSearchService { @GetHttpInterface("/place/text") public HttpResponse<String> getSearch(@QueryPar("keywords") String keywords,@QueryPar("types") String types,@QueryPar("region") String region,@QueryPar("page_size") String page_size,@QueryPar("page_num") String page_num ,@QueryPar("show_fields")String show_fields, @QueryPar("key") String key); @GetHttpInterface("/place/polygon") public HttpResponse<String> searchByPolygon(@QueryPar("polygon") String polygon,@QueryPar("keywords") String keywords,@QueryPar("types") String types,@QueryPar("page_size") String page_size,@QueryPar("page_num") String page_num ,@QueryPar("show_fields")String show_fields, @QueryPar("key") String key); } 在上面的例子中，创建了两个访问接口。第一个方法是根据关键字来调用检索，第二个 方法是根据一个polygon范围来进行检索。上述接口中的参数说明已经在第一节中进行讲解，可以往前搜索以下。
3、业务调用集成
接下来讲解如何在Java当中调用Uniapi定义的接口，根据我们传入的参数来查询目标POI。比如我们需要查询湖南省长沙市岳麓区（代码：430104）的餐饮服务（pot type：050000）的数据，每页数据返回的大小为20条数据。集成的访问代码如下：
package com.yelang.project.unihttp; import org.geotools.geometry.jts.JTSFactoryFinder; import org.junit.Test; import org.junit.runner.RunWith; import org.locationtech.jts.geom.Coordinate; import org.locationtech.jts.geom.GeometryFactory; import org.locationtech.jts.geom.LinearRing; import org.locationtech.jts.geom.Polygon; 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.common.utils.geo.CoordinateTransformUtil; import com.yelang.project.education.domain.amap.AmapSearchVO; import com.yelang.project.thridinterface.AmapSearchService; @SpringBootTest @RunWith(SpringRunner.class) public class AmaPOISearchCase { private static final String AMAP_CLIENT_AK = "申请的访问key"; @Autowired private AmapSearchService amapSearchService; /** * - 关键字搜索 API 服务地址 * @throws InterruptedException */ @Test public void searchByKeyWordOrTypies() throws InterruptedException { String; String types = "050000"; String page_size = "20"; String region = "430104"; String show_fields = "children,business,indoor,navi,photos"; HttpResponse<String> result = null; for(int i = 1;i<= 1;i++) { result = amapSearchService.getSearch(keywords, types,region, page_size,String.valueOf(i),show_fields,AMAP_CLIENT_AK); System.out.println(result.getBodyResult()); Thread.sleep(3000L);//休眠3秒 } } }接下来我们运行上面的程序，可以在控制台中看到以下的输出：
看到以下的信息说明返回成功，接口成功调用，下面我们将返回结果进行格式化。
三、常见问题与优化
在实际开发过程中，开发者可能会遇到一些常见问题，如API调用频率限制、数据解析错误、网络请求超时等。针对这些问题，开发者可以通过合理的代码设计和异常处理机制，确保系统的稳定性和可靠性。此外，高德开放平台还提供了详细的开发文档和技术支持，帮助开发者快速解决遇到的问题。
在实际项目开发过程中，需要注意相关key的保护问题。这里使用的明文保存的方式，在使用高德API时需要注意的安全性问题，如API Key的保护、数据传输的加密等。可以采用加密的方式对明文进行保存，在访问时进行解密即可。
四、总结
以上就是本文的主要内容，本文将以搜索POI2.0为例，详细介绍如何在Java项目中集成高德开放平台的WebAPI，并实现高效的POI搜索功能。示例将涵盖从API密钥的获取、HTTP请求的发送、数据的解析到最终结果的展示等完整流程。通过本文的学习，开发者将能够掌握Java与高德开放平台WebAPI集成的基本方法，并能够根据实际需求，灵活应用这些技术解决实际问题。行文仓促，定有不足之处，欢迎各位朋友在评论区批评指正，不胜感激。
