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

夜郎king2026-03-24 8:43

目录

一、前言

[1.1 业务背景](#1.1 业务背景)

[1.2 现有服务的痛点](#1.2 现有服务的痛点)

二、百度海外天气API

[2.1 API信息与请求参数](#2.1 API信息与请求参数)

[2.2 返回参数解析](#2.2 返回参数解析)

三、Java实战

[3.1 前置准备工作](#3.1 前置准备工作)

[3.2 UniHttp接口定义（通用HTTP工具类）](#3.2 UniHttp接口定义（通用HTTP工具类）)

[3.3 实际调用：百度海外天气工具类](#3.3 实际调用：百度海外天气工具类)

四、成果展示

[4.1 按海外城市行政区划编码检索](#4.1 按海外城市行政区划编码检索)

[4.2 按海外经纬度检索](#4.2 按海外经纬度检索)

五、总结

[5.1 核心技术亮点总结](#5.1 核心技术亮点总结)

[5.2 开发注意事项](#5.2 开发注意事项)

一、前言

1.1 业务背景

随着互联网全球化、跨境业务常态化以及GIS地理信息系统的广泛普及，海外城市实时气象数据早已不再是单纯的民生查询需求，而是成为众多后端业务系统、物联网平台、跨境服务应用的核心基础数据支撑，应用场景覆盖各行各业，刚需属性极强。在跨境文旅与出行服务 领域，海外出行APP、国际机票酒店预订平台，需要实时展示目的地城市的天气状况，帮助用户规划行程、规避恶劣天气，提升用户体验与平台实用性；在国际物流与跨境电商 场景中，物流调度系统、海外仓储管理平台，需要依托海外天气数据预判运输延误、调整配送方案，保障跨境货物运输效率；在GIS地理信息与物联网行业，海外站点监控、跨境水利监测、全球点位气象图层叠加等业务，更是离不开精准的经纬度对应天气数据，支撑系统实现时空数据与气象数据的联动分析。

除此之外，海外留学服务平台、跨国企业办公系统、户外跨境作业设备监控等场景，也都对稳定、免费、易接入的海外天气接口有强烈需求。对于Java后端开发者而言，快速搭建一套轻量、稳定的海外天气获取服务，既能满足业务刚需，也能完善系统的基础数据能力，是极具实用价值的技术落地场景。

1.2 现有服务的痛点

尽管国内天气接口资源丰富，但放眼海外气象数据获取领域，市面上的服务普遍存在诸多短板，导致开发者在实际开发中屡屡受阻，具体痛点主要集中在以下几点：

  • 服务覆盖范围受限：绝大多数免费国内天气接口，仅支持国内城市数据查询，完全不覆盖海外地区，无法满足跨境业务的基础需求；少数支持海外的接口，也仅覆盖部分主流城市，小众海外城市、偏远地区数据缺失严重。

  • 成本与门槛过高：专业海外气象商业接口，要么收费高昂、按调用次数计费，中小企业和个人开发者难以承担；要么需要企业资质认证、签约审核，个人项目根本无法接入，开发成本和准入门槛双高。

  • 接口集成难度大：部分海外开源气象接口，协议复杂、鉴权繁琐，部分接口还存在地域访问限制、国内调用延迟高、数据格式不规范等问题，Java后端集成需要额外处理网络、编码、异常等诸多问题，开发效率极低。

  • 适配场景单一：现有接口大多仅支持城市名称查询，不支持GIS场景常用的经纬度检索，无法适配地理信息系统、全球点位监控等专业化需求，实用性大打折扣。

针对以上痛点，本文选择百度地图开放平台海外天气API作为数据来源，结合Java原生开发，打造一套零额外依赖、轻量易集成、支持双模式查询的海外天气获取工具，免费额度充足，接入流程简单，解决个人开发者与中小企业的海外天气数据获取难题。

二、百度海外天气API

2.1 API信息与请求参数

百度海外天气API属于百度地图开放平台，采用HTTPS协议，支持GET请求方式，接口稳定、响应速度快，访问无延迟，核心支持海外城市行政区编码 和经纬度坐标两种查询方式，适配不同业务场景。关于百度天气服务在之前的内容中也曾经重点详细的讲解过。

参数名 数据类型 必选 默认值 描述信息
district_id string 否 无 海外城市行政区划编码海外城市行政区划编码为自定义，只支持海外天气查询服务使用），和location二选一
location double 否 无 经纬度，经度在前纬度在后，逗号分隔。支持类型：bd09mc/bd09ll/wgs84/gcj02。
ak string 是 无 开发者密钥，可在API控制台申请获得
data_type string 是 无 请求数据类型。数据类型有：now/fc/index/alert/fc_hour/all，控制返回内容
output string 否 json 返回格式，目前支持json/xml
language string 否 cn 语言类型。语言类型有: cn/en，分别表示中文和英文， 默认中文。目前仅支持行政区划显示英文。
coordtype string 否 wgs84 支持类型:wgs84/bd09ll/bd09mc/gcj02

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

2.2 返回参数解析

接口请求成功后返回标准JSON格式数据，核心返回字段清晰易懂，无需复杂解析，关键参数分为三大模块：

  • 状态标识：status字段，0表示请求成功，非0为对应错误码，方便快速判断接口调用结果；

  • 位置信息：result.location下包含城市名称、国家、经纬度、行政区划编码等基础地理信息，确认查询目标准确性；

  • 实时天气数据：result.now为核心业务数据，包含实时温度、体感温度、湿度、风向、风力、天气现象（晴、雨、雪等）、气压等完整气象数据；

  • 更新时间：result.update_time标记气象数据的最新更新时间，确保数据时效性。

关于天气的返回参数，见：GSON 框架下百度天气 JSON 数据转 JavaBean 的实战攻略。

三、Java实战

3.1 前置准备工作

  1. 注册百度地图开放平台账号，进入控制台创建应用，选择服务端应用类型，获取AK密钥；

  2. 确认应用开通天气接口权限（免费默认开通）；

  3. 搭建基础Java项目，引入UniHttp依赖，SpringBoot项目也可直接复用。

3.2 UniHttp接口定义

为了简化HTTP请求流程，避免引入HttpClient、OkHttp等第三方依赖，本文使用UniHttp工具类，实现GET请求功能，代码简洁、无冗余，适配所有Java项目，兼容性极强。核心代码如下：

java 复制代码 
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;
/**
 * -百度海外天气服务
 * @author 夜郎king
 */
@HttpApi(url = "https://api.map.baidu.com/weather_abroad/v1")
public interface BaiduWeatherAbroadService {
	/**
	 * -通过行政区划代码查询实时天气信息及未来7天天气预报。（注意：如果district_id和location同时传，默认以district_id为准；）
	 * @param district_id 海外城市行政区划编码海外城市行政区划编码为自定义，只支持海外天气查询服务使用），和location二选一
	 * @param location 经纬度，经度在前纬度在后，逗号分隔。支持类型：bd09mc/bd09ll/wgs84/gcj02。这里官网定义的数据类型为Double，应该是标注有误
	 * @param ak 开发者密钥
	 * @param data_type 请求数据类型。类型有：now/fc/index/alert/fc_hour/all，控制返回内容
	 * @param output 返回格式，目前支持json/xml
	 * @param language 语言类型。语言类型有: cn/en，分别表示中文和英文， 默认中文。
	 * @param coordtype 支持类型:wgs84/bd09ll/bd09mc/gcj02
	 * @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的测试集成方式进行演示。核心代码如下：

java 复制代码 
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;
/**
 * - 百度海外天气测试类
 * @author 夜郎king
 *
 */
@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 按编码检索

该查询方式适合固定海外城市、业务系统配置化查询场景，只需提前获取目标海外城市的district_id，传入方法即可快速获取精准天气数据，数据稳定无延迟。海外城市的行政区划id百度提供了完整的列表，大家下载到本地即可，这里以伊朗首都德黑兰为例，在Excel表格中查找到具体的区划编码，如下：

测试效果：传入德黑兰对应行政区编码：IRN10001001001，控制台成功返回德黑兰城市名称、实时气温、湿度、风向、天气状况、数据更新时间等完整信息，数据精准匹配当地实时气象，无乱码、无数据缺失，适配后台定时同步、固定城市天气展示等业务。

4.2 按经纬度检索

海外天气服务除了支持按照行政区划来查询外，还支持按照经纬度来进行查询。该模式是GIS地理信息系统、全球点位监控场景的核心适配方式，无需提前知晓城市名称，只需传入目标点位的经纬度坐标，接口会自动匹配所属海外城市，返回对应实时天气数据。这里以耶路撒冷为例：

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

五、总结

以上就是本文的主要内容。本篇实战文章围绕Java后端开发者的实际业务痛点，完整落地了基于百度天气API的海外城市实时天气获取功能，从业务背景分析、接口讲解、代码封装到成果验证，全程覆盖开发全流程，代码可直接复制运行。

5.1 核心技术亮点总结

  • 零依赖轻量实现：全程采用JDK原生代码开发，未引入任何第三方框架和依赖包，无论是普通Java项目、SpringBoot/SpringMvc项目，还是老旧Java后端系统，都能无缝接入、直接复用，兼容性拉满，不会对原有项目造成任何侵入。

  • 双查询模式全覆盖：同时支持海外城市行政区编码和经纬度坐标查询，兼顾普通业务系统和GIS地理信息专业场景，解决了市面上大部分接口场景单一的短板，适用范围极广。

  • 低成本高稳定性：依托百度地图开放平台免费接口，个人开发者和中小企业均可免费使用，免费调用额度完全满足日常开发和小规模业务需求，规避商业接口高额成本；接口国内访问稳定、延迟低，数据实时性强，无地域访问限制。

5.2 开发注意事项

  • 百度AK密钥需妥善保管，建议在项目中通过配置文件注入，不要硬编码到工具类中；

  • 海外城市行政区编码需通过百度地图开放平台官方渠道查询，确保编码准确，避免查询失败；

  • 经纬度坐标格式需严格遵循"英文逗号分隔、无空格"规范，防止格式错误导致接口调用失败。

整体而言，这套Java海外天气获取方案，完美平衡了开发成本、接入难度和实用性，精准解决了跨境业务、GIS系统中海外气象数据获取的核心痛点，非常适合Java后端新手学习实战，也能直接落地到实际项目中，是一款高效实用的后端工具类实现。行文仓促，难免有许多不足之处，如果在实操中遇到问题，欢迎在评论区评论交流～。

相关推荐
夜郎king4 个月前
基于Java的百度地图路线规划服务开发全攻略
java集成百度地图·百度开放平台·百度路径规划·unihttp集成百度地图·java转换百度地图服务
夜郎king5 个月前
基于百度地铁 API 的长沙地铁站点详情查询与路线导航实践
百度开放平台·百度地图导航实现·百度地图地铁js
热门推荐
01GitHub 镜像站点02Qwen3.5 开源全解析：从 0.8B 到 397B，代际升级 + 全场景选型指南03围棋-html版本04小黑课堂计算机二级WPSoffice题库软件下载安装教程（2026年3月最新版）05班级宠物园部署指南06OpenClaw 使用和管理 MCP 完全指南07UV安装并设置国内源08“wsl --install -d Ubuntu-22.04”下载慢，中国地区离线安装 Ubuntu 22.04 WSL方法（亲测2025年5月6日）09AI 编程三剑客：Spec-Kit、OpenSpec、Superpowers 深度对比与实战指南10让 Trae IDE 智能体 “读懂”文档 Excel+PDF+DOCX ：mcp-documents-reader 工具使用指南