以下是文章《基于Java和高德开放平台的WebAPI集成实践——以搜索POI 2.0为例》的完整技术实践内容，适用于技术博客、项目笔记或技术演讲参考：

基于 Java 和高德开放平台的 WebAPI 集成实践 —— 以搜索 POI 2.0 为例

高德开放平台提供了丰富的地图服务接口，其中「搜索 POI（Point of Interest）2.0」接口是最常用的数据服务之一，适合用于城市服务、出行工具、LBS 应用等场景。本篇文章将基于 Java 实现对 POI 搜索接口的完整对接，涵盖参数构建、接口请求、响应解析及注意事项。

📌 目录

  1. 接口简介：什么是 POI 搜索 2.0？
  2. 获取高德 WebAPI Key
  3. 接口文档解析与关键参数
  4. Java 项目环境准备
  5. 编写 Java 请求 POI 接口代码
  6. 返回结果解析与实体封装
  7. 错误处理与接口限速
  8. 实战案例：输入关键词获取附近餐厅
  9. 常见问题与调试建议
  10. 总结与扩展方向

1. 接口简介：什么是 POI 搜索 2.0？

POI（Point of Interest）即兴趣点，例如商店、餐馆、医院、银行等。高德地图的「搜索 POI 2.0」接口支持用户通过关键词、经纬度等方式查找指定城市或区域内的 POI 数据。

接口文档地址（需登录）：
👉 https://lbs.amap.com/api/webservice/guide/api/search

2. 获取高德 WebAPI Key

要使用 Web 服务 API，需要在高德开放平台控制台中创建应用并获取 key：

  1. 登录 高德开放平台官网
  2. 创建应用并启用“Web服务API”权限
  3. 获取你的 key（假设为 your_api_key_here）

3. 接口文档解析与关键参数

请求地址：

https://restapi.amap.com/v5/place/text

常用参数：

参数说明示例
key高德 API Keyyour_api_key_here
keywords搜索关键词（多个词用 `` 分隔）
city城市名或行政区编码北京
citylimit是否限制在当前城市true
page_size每页条数（1-25）10
page_num页码1
output返回格式json

4. Java 项目环境准备

我们使用标准的 Maven 工程来完成：

<!-- pom.xml 添加依赖 -->
<dependencies>
    <dependency>
        <groupId>com.squareup.okhttp3</groupId>
        <artifactId>okhttp</artifactId>
        <version>4.12.0</version>
    </dependency>
    <dependency>
        <groupId>com.google.code.gson</groupId>
        <artifactId>gson</artifactId>
        <version>2.10.1</version>
    </dependency>
</dependencies>

5. 编写 Java 请求 POI 接口代码

import okhttp3.*;
import java.io.IOException;

public class GaoDePoiSearcher {
    private static final String API_KEY = "your_api_key_here";
    private static final String BASE_URL = "https://restapi.amap.com/v5/place/text";

    public static String searchPoi(String keywords, String city, int page, int size) throws IOException {
        HttpUrl url = HttpUrl.parse(BASE_URL).newBuilder()
                .addQueryParameter("key", API_KEY)
                .addQueryParameter("keywords", keywords)
                .addQueryParameter("city", city)
                .addQueryParameter("citylimit", "true")
                .addQueryParameter("page_size", String.valueOf(size))
                .addQueryParameter("page_num", String.valueOf(page))
                .addQueryParameter("output", "json")
                .build();

        OkHttpClient client = new OkHttpClient();
        Request request = new Request.Builder().url(url).get().build();
        try (Response response = client.newCall(request).execute()) {
            if (response.isSuccessful()) return response.body().string();
            else throw new IOException("Unexpected code " + response);
        }
    }
}

6. 返回结果解析与实体封装

高德接口返回的 JSON 结构如下（简略）：

{
  "status": "1",
  "count": "2",
  "pois": [
    {
      "name": "海底捞",
      "address": "中关村大街",
      "location": "116.331398,39.897445",
      "type": "中餐馆"
    }
  ]
}

我们可以定义对应的 Java 实体类：

class Poi {
    private String name;
    private String address;
    private String location;
    private String type;

    // Getters / toString() 可省略
}

解析：

import com.google.gson.*;

public class JsonParserUtil {
    public static List<Poi> parsePois(String json) {
        JsonObject obj = JsonParser.parseString(json).getAsJsonObject();
        JsonArray pois = obj.getAsJsonArray("pois");

        List<Poi> result = new ArrayList<>();
        for (JsonElement el : pois) {
            JsonObject o = el.getAsJsonObject();
            Poi poi = new Poi();
            poi.name = o.get("name").getAsString();
            poi.address = o.get("address").getAsString();
            poi.location = o.get("location").getAsString();
            poi.type = o.get("type").getAsString();
            result.add(poi);
        }
        return result;
    }
}

7. 错误处理与接口限速

  • 限频策略： 每个 key 的接口调用频率有限，详见高德后台；
  • 返回状态判断： 返回的 JSON 字段 status=1 为成功，否则为失败；
  • 防封策略： 推荐添加 User-Agent 头模拟浏览器请求。

8. 实战案例：输入关键词获取附近餐厅

主函数调用：

public class Main {
    public static void main(String[] args) throws IOException {
        String result = GaoDePoiSearcher.searchPoi("餐厅", "北京", 1, 5);
        List<Poi> pois = JsonParserUtil.parsePois(result);
        pois.forEach(System.out::println);
    }
}

输出：

Poi{name='海底捞', address='朝阳区XXX', location='116.4,39.9', type='中餐馆'}
Poi{name='西贝莜面村', address='XXX', ...}
...

9. 常见问题与调试建议

问题解决建议
请求返回 status=0检查 key 是否正确，是否启用 WebAPI
请求成功但返回为空检查关键词拼写，尝试加上城市限制
中文乱码使用 UTF-8 发送请求，设置 header
频率限制触发更换 key 或等待冷却时间

10. 总结与扩展方向

本篇介绍了使用 Java 调用高德 POI 2.0 WebAPI 的完整流程，包括：

  • 请求构建与 OkHttp 使用
  • JSON 响应解析
  • 实体映射与异常处理

✅ 可扩展方向：

  • 搜索 POI 周边（/place/around）
  • 关键字联想（/assistant/inputtips）
  • 使用 Spring Boot 构建 LBS 后台服务
  • 将 POI 数据与地图可视化（如 Echarts + 高德地图叠加）

🔗 参考链接

如需将其整合进 Spring Boot 工程，或封装为统一服务层模块，可继续留言。我可以帮你生成标准 REST 接口版本的代码结构。