Java 基于百度 API 实现海外城市实时天气获取

注意：如果 district_id 和 location 同时传，默认以 district_id 为准。

2.2 返回参数解析

接口请求成功后返回标准 JSON 格式数据，关键参数分为三大模块：

• 状态标识：status 字段，0 表示请求成功。
• 位置信息：result.location 下包含城市名称、国家、经纬度等。
• 实时天气数据：result.now 为核心业务数据，包含温度、湿度、风向等。
• 更新时间：result.update_time 标记气象数据的最新更新时间。

三、Java 实战

3.1 前置准备工作

1. 注册百度地图开放平台账号，进入控制台创建应用，选择服务端应用类型，获取 AK 密钥；
2. 确认应用开通天气接口权限（免费默认开通）；
3. 搭建基础 Java 项目，引入 UniHttp 依赖，SpringBoot 项目也可直接复用。

3.2 UniHttp 接口定义

为了简化 HTTP 请求流程，避免引入 HttpClient、OkHttp 等第三方依赖，本文使用 UniHttp 工具类。核心代码如下：

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://api.map.baidu.com/weather_abroad/v1")
public interface BaiduWeatherAbroadService {
    /**
     * -通过行政区划代码查询实时天气信息及未来 7 天天气预报。
     * @param district_id 海外城市行政区划编码
     * @param location 经纬度，经度在前纬度在后，逗号分隔
     * @param ak 开发者密钥
     * @param data_type 请求数据类型
     * @param output 返回格式
     * @param language 语言类型
     * @param coordtype 坐标类型
     * @return
     */
    @GetHttpInterface("/")
    public HttpResponse<String> query(@QueryPar("district_id") String district_id,
                                      @QueryPar("location") String location,
                                      @QueryPar("ak") String ak,
                                      @QueryPar("data_type") String data_type,
                                      @QueryPar("output") String output,
                                      @QueryPar("language") String language,
                                      @QueryPar("coordtype") String coordtype);
}

3.3 实际调用

封装专属天气查询工具类，整合两种查询方式，将 AK 和接口地址抽离为演示示例。这里使用 Junit 的测试集成方式进行演示。

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.meteorology.domain.BdWeatherDTO;
import com.yelang.project.meteorology.domain.WeatherInfoDTO;
import com.yelang.project.thridinterface.BaiduWeatherAbroadService;

/**
 * - 百度海外天气测试类
 */
@SpringBootTest
@RunWith(SpringRunner.class)
public class BaiduWeatherAbroadServiceCase {
    private static final String BAIDU_DEFAULT_AK = "yourak";
    private static final String DATA_TYPE = "all";
    private static final String OUTPUT = "json";
    private static final String LANGUAGE = "cn";
    private static final String COORDTYPE = "wgs84";

    @Autowired
    private BaiduWeatherAbroadService bdWeatherAbroadService;

    /**
     * - 根据行政区代号查询外国天气
     */
    @Test
    public void queryBydistrictId() {
        String district_id = "IRN10001001001"; // 德黑兰
        HttpResponse<String> result = bdWeatherAbroadService.query(district_id, null, BAIDU_DEFAULT_AK, DATA_TYPE, OUTPUT, LANGUAGE, COORDTYPE);
        System.out.println(result.getBodyResult());
        Gson gson = new Gson();
        BdWeatherDTO bdWeatherInfo = gson.fromJson(result.getBodyResult(), BdWeatherDTO.class);
        WeatherInfoDTO bdResult = bdWeatherInfo.getResult();
        System.out.println(bdResult.getWeatherNow());
        System.out.println(bdResult.getAlerts());
        System.out.println(bdResult.getIndexes());
        System.out.println(bdResult.getForecasts());
        System.out.println(bdResult.getForecastHours());
    }

    /**
     * - 根据经纬度查外国天气
     */
    @Test
    public void queryLocation() {
        String location = "35.03705894,31.73021175"; // 以色列
        HttpResponse<String> result = bdWeatherAbroadService.query(null, location, BAIDU_DEFAULT_AK, DATA_TYPE, OUTPUT, LANGUAGE, COORDTYPE);
        System.out.println(result.getBodyResult());
        Gson gson = new Gson();
        BdWeatherDTO bdWeatherInfo = gson.fromJson(result.getBodyResult(), BdWeatherDTO.class);
        WeatherInfoDTO bdResult = bdWeatherInfo.getResult();
        System.out.println(bdResult.getWeatherNow());
        System.out.println(bdResult.getAlerts());
        System.out.println(bdResult.getIndexes());
        System.out.println(bdResult.getForecasts());
        System.out.println(bdResult.getForecastHours());
    }
}

四、成果展示

4.1 按编码检索

该查询方式适合固定海外城市、业务系统配置化查询场景。海外城市的行政区划 id 百度提供了完整的列表，大家下载到本地即可，这里以伊朗首都德黑兰为例。

测试效果：传入德黑兰对应行政区编码：IRN10001001001，控制台成功返回德黑兰城市名称、实时气温、湿度、风向、天气状况、数据更新时间等完整信息。

4.2 按经纬度检索

该模式是 GIS 地理信息系统、全球点位监控场景的核心适配方式，无需提前知晓城市名称，只需传入目标点位的经纬度坐标。

测试效果：传入耶路撒冷经纬度坐标（35.03705894,31.73021175），接口快速定位对应城市，返回完整气象数据，完美适配地图点位气象叠加、跨境设备监控等专业化需求，解决了传统接口不支持 GIS 坐标查询的痛点，实用性强。

五、总结

以上为方案主要内容。本篇实战文章围绕 Java 后端开发者的实际业务痛点，完整落地了基于百度天气 API 的海外城市实时天气获取功能。

5.1 核心技术亮点总结

• 零依赖轻量实现：全程采用 JDK 原生代码开发，未引入任何第三方框架和依赖包，兼容性好。
• 双查询模式全覆盖：同时支持海外城市行政区编码和经纬度坐标查询，兼顾普通业务系统和 GIS 地理信息专业场景。
• 低成本高稳定性：依托百度地图开放平台免费接口，个人开发者和中小企业均可免费使用；接口国内访问稳定、延迟低。

5.2 开发注意事项

• 百度 AK 密钥需妥善保管，建议在项目中通过配置文件注入，不要硬编码到工具类中；
• 海外城市行政区编码需通过百度地图开放平台官方渠道查询，确保编码准确；
• 经纬度坐标格式需严格遵循'英文逗号分隔、无空格'规范，防止格式错误导致接口调用失败。

整体而言，这套 Java 海外天气获取方案，平衡了开发成本、接入难度和实用性，精准解决了跨境业务、GIS 系统中海外气象数据获取的核心痛点。