基于Java和高德开放平台的WebAPI集成实践-以搜索POI2.0为例
目录
前言
一、高德搜索API简介
1、高德开放平台
2、搜索功能介绍
3、部分API介绍
二、Uniapi集成高德API
1、API集成流程
2、访问接口的定义
3、业务调用集成
三、常见问题与优化
四、总结
前言
在当今数字化时代，地理信息系统（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 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 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 keywords = ""; String types = "050000"; String page_size = "20"; String region = "430104"; String show_fields = "children,business,indoor,navi,photos"; HttpResponse result = null; for(int i = 1;i
