Java 集成高德开放平台 WebAPI 实现 POI 搜索

Java 集成高德开放平台 WebAPI 实现 POI 搜索

高德搜索 API 简介

高德开放平台

高德开放平台提供了丰富的 WebAPI 接口，帮助开发者快速集成地图、导航、搜索等功能。其中，POI（Point of Interest）搜索是许多应用场景中的关键功能，它能够帮助用户快速找到附近的兴趣点，如餐馆、酒店、加油站等。

搜索功能介绍

平台的 POI 搜索 API 提供了多种搜索方式，包括关键字搜索、周边搜索、多边形搜索等。

• 关键字搜索：开发者可通过文本关键字搜索地点信息，文本可以是结构化地址，例如：北京市朝阳区望京阜荣街 10 号；也可以是 POI 名称，例如：首开广场。
• 周边搜索：开发者可设置圆心和半径，搜索圆形区域内的地点信息。
• 多边形区域搜索：开发者可设置首尾连接的几何点组成多边形区域，搜索坐标对应多边形内的地点信息。
• ID 搜索：开发者可通过已知的地点 ID（POI ID）搜索对应地点信息，建议结合输入提示接口使用。

通过这些 API，开发者可以根据用户的需求，灵活地获取所需的 POI 信息。POI 搜索 2.0 版本在原有功能的基础上，进一步优化了搜索算法，提升了搜索结果的准确性和响应速度。

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，相互之间用'	'分隔	可选（keyword 或者 types 二选一必填）
region	搜索区划	增加指定区域内数据召回权重，如需严格限制召回数据在区域内，请搭配使用 city_limit 参数，可输入 citycode，adcode，cityname	可选	无，默认全国范围内搜索
city_limit	指定城市数据召回限制	可选值：true/false。为 true 时，仅召回 region 对应区域内数据	可选	false
show_fields	返回结果控制	show_fields 用来筛选 response 结果中可选字段。多个字段间采用','进行分割；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 代表正确
count	string	单次请求返回的实际 poi 点的个数
pois	object	返回的 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, business, indoor, navi, photos 等详细信息。

Uniapi 集成高德 API

本节详细介绍如何在 Java 中使用 Uniapi 来集成高德 api 实现相关的检索服务。

集成流程

在 Java 项目中集成高德开放平台的 WebAPI，通常需要以下几个步骤：首先，开发者需要在高德开放平台注册账号，并创建应用以获取 API 密钥（Key）。其次，开发者需要在 Java 项目中引入 HTTP 客户端库，用于发送 HTTP 请求并接收 API 的响应。本文将以 Uniapi 为例重点介绍。接下来，开发者需要根据高德 API 的文档，构建符合要求的请求 URL，并处理 API 返回的数据。

接口定义

这里介绍如何在 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 范围来进行检索。

业务调用

接下来讲解如何在 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 服务地址
     */
    @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<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 秒
        }
    }
}

运行程序后，控制台将输出返回的 JSON 数据。看到以下的信息说明返回成功，接口成功调用。

常见问题与优化

在实际开发过程中，开发者可能会遇到一些常见问题，如 API 调用频率限制、数据解析错误、网络请求超时等。针对这些问题，开发者可以通过合理的代码设计和异常处理机制，确保系统的稳定性和可靠性。

在实际项目开发过程中，需要注意相关 key 的保护问题。这里使用的明文保存的方式，在使用高德 API 时需要注意的安全性问题，如 API Key 的保护、数据传输的加密等。可以采用加密的方式对明文进行保存，在访问时进行解密即可。

总结

本文详细介绍了如何在 Java 项目中集成高德开放平台的 WebAPI，并实现高效的 POI 搜索功能。示例涵盖了从 API 密钥的获取、HTTP 请求的发送、数据的解析到最终结果的展示等完整流程。开发者可根据实际需求，灵活应用这些技术解决实际问题。