Java 集成高德开放平台 Web API 实践：POI 搜索 2.0 示例

返回结果

poi 对象包含以下字段：

注意以下字段如需返回需要通过'show_fields'进行参数类设置：children, business, indoor, navi, photos 等详细子字段结构参考官方文档。

二、Uniapi 集成高德 API

本节详细介绍如何在 Java 中使用 Uniapi 来集成高德 api 实现相关的检索服务。主要从以下三个部分进行介绍：第一是介绍 API 的集成流程；第二是介绍如何在 Uniapi 中定义接口；第三是介绍如何在业务中进行集成。

1、API 集成流程

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

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.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.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<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 的保护、数据传输的加密等。可以采用加密的方式对明文进行保存，在访问时进行解密即可。

四、总结

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