手把手教你调用羲和平台API:自动获取未来7天气象数据的5种实战方法
最近在做一个新能源项目的预测模型,需要连续获取特定区域未来一周的精细化气象数据。手动下载不仅效率低下,还容易出错。在对比了几个主流的气象数据源后,我最终选择了羲和能源气象大数据平台。它的API接口设计得相当清晰,数据维度丰富,特别是对未来7天的预测数据支持,正好契合我的需求。这篇文章,我就把自己从零开始,踩过几个小坑,最终实现稳定、自动化数据采集的完整过程分享出来。无论你是需要将气象数据集成到业务系统的开发者,还是需要进行数据分析的研究者,这几种实战方法应该都能给你提供直接的参考。
1. 环境准备与平台接入基础
在开始写第一行代码之前,我们需要先把“战场”布置好。调用任何第三方API,第一步永远是搞清楚它的“游戏规则”——也就是官方文档。羲和平台的文档结构比较清晰,核心在于理解其认证方式和数据请求的基本格式。
首先,你需要注册一个平台账号。这个过程在官网就能完成,注册后通常可以在个人中心找到API相关的管理页面。这里你会获得两个至关重要的信息:API Key(或称为Access Token) 和 API 请求的基础地址(Base URL)。API Key是你的身份凭证,每次请求都必须携带;Base URL则是所有API调用的起点。
我建议在项目初期就建立一个独立的配置文件来管理这些敏感信息,而不是硬编码在脚本里。一个简单的 config.py 或 .env 文件是不错的选择。
# config.py 示例
XIHE_API_BASE_URL = "https://api.xihe-energy.com/v1"
XIHE_API_KEY = "your_actual_api_key_here" # 请替换为你的真实Key
对于Python环境,我们主要会用到 requests 库来处理HTTP请求,以及 pandas 和 json 来处理返回的数据。如果你还没有安装,可以通过pip快速安装:
pip install requests pandas
注意:请务必保管好你的API Key,不要将其提交到公开的代码仓库(如GitHub)。使用
.gitignore文件忽略你的配置文件是一个好习惯。
一个健壮的API调用程序,必须考虑网络异常和平台响应异常。因此,在构建最核心的请求函数时,我会习惯性地加上错误处理和重试机制。下面是一个基础的、可复用的请求函数模板:
import requests
import time
from config import XIHE_API_BASE_URL, XIHE_API_KEY
def make_xihe_request(endpoint, params=None, max_retries=3):
"""
向羲和平台发起API请求的通用函数。
Args:
endpoint (str): API端点路径,例如 '/weather/forecast'
params (dict): 请求参数字典
max_retries (int): 最大重试次数
Returns:
dict: 解析后的JSON响应数据,如果失败则返回None
"""
url = f"{XIHE_API_BASE_URL}{endpoint}"
headers = {
"Authorization": f"Bearer {XIHE_API_KEY}",
"Content-Type": "application/json"
}
for attempt in range(max_retries):
try:
response = requests.get(url, headers=headers, params=params, timeout=30)
response.raise_for_status() # 如果状态码不是200,抛出HTTPError
return response.json()
except requests.exceptions.RequestException as e:
print(f"请求失败 (尝试 {attempt + 1}/{max_retries}): {e}")
if attempt < max_retries - 1:
wait_time = 2 ** attempt # 指数退避策略
print(f"等待 {wait_time} 秒后重试...")
time.sleep(wait_time)
else:
print("已达到最大重试次数,放弃请求。")
return None
# 示例:测试API连通性
if __name__ == "__main__":
test_result = make_xihe_request('/test/ping') # 假设存在一个测试端点
if test_result:
print("API连接测试成功!")
这个函数封装了认证头添加、异常捕获和简单的重试逻辑,是我们后续所有方法的基础。接下来,我们就可以利用它去获取实际的气象数据了。
2. 方法一:基础单点数据获取
这是最直接、最常见的需求:获取某个特定地理坐标点未来7天的气象数据。羲和平台提供了丰富的参数,我们需要搞清楚哪些是必填,哪些是可选,以及数据返回的格式。
首先,找到获取预报数据的API端点。根据文档,可能是类似于 /weather/forecast 这样的路径。关键的请求参数通常包括:
- location (必需): 指定地点的经纬度,格式通常是
经度,纬度,例如116.4,39.9代表北京附近。 - variables (可选): 需要获取的气象要素。羲和平台支持多达11种数据,如温度(
temperature)、降水量(precipitation)、风速(wind_speed)、风向(wind_direction)、相对湿度(humidity)等。如果不指定,可能返回所有可用数据。 - start_date / end_date (可选): 时间范围。对于预报数据,通常我们只需要指定
start_date为今天,平台会自动返回未来7天的数据。 - output_format (可选): 返回数据的格式,常见的有
json和csv。
假设我们要获取北京未来7天所有气象要素的预报,代码如下:
def get_7day_forecast_single_point(lon, lat):
"""
获取单个坐标点未来7天的气象预报数据。
"""
endpoint = "/weather/forecast"
params = {
"location": f"{lon},{lat}",
# "variables": "temperature,precipitation,wind_speed", # 可以指定特定变量
"start_date": "2023-11-15", # 应动态获取当前日期
"output_format": "json"
}
data = make_xihe_request(endpoint, params)
if data and data.get('status') == 'success': # 根据实际API响应结构调整
forecast_list = data.get('data', [])
# 使用pandas进行初步整理
import pandas as pd
df = pd.DataFrame(forecast_list)
# 可能需要对时间戳等字段进行转换
if 'time' in df.columns:
df['time'] = pd.to_datetime(df['time'])
print(f"成功获取到 {len(df)} 条预报数据。")
print(df.head()) # 预览前几行
return df
else:
print(f"数据获取失败。响应: {data}")
return None
# 调用示例
beijing_forecast = get_7day_forecast_single_point(116.4, 39.9)
返回的数据很可能是一个包含时间序列的列表。每个时间点(例如逐小时)对应一组气象要素的值。这里最容易遇到的坑是时间戳的时区问题。平台返回的时间可能是UTC时间,也可能是本地时间,务必查看文档确认。如果需要进行时区转换,可以使用 pandas 的 tz_convert 方法。
提示:在实际项目中,
start_date参数应该通过程序动态生成,例如使用datetime.datetime.now().strftime('%Y-%m-%d'),而不是像我示例中那样写死。
3. 方法二:批量获取多区域数据
很多时候,我们的业务需要监控多个地点的气象情况,比如一个拥有多个风电场的新能源公司。逐一点击调用API在效率上是不可接受的。这时,我们需要实现批量请求。
批量处理有两种主流思路:
- 串行循环:简单直接,但总耗时是各个请求时间的总和,速度慢。
- 并发请求:利用多线程或异步IO,同时发起多个请求,大幅缩短总耗时。
对于API调用这种I/O密集型任务,并发是更优的选择。Python的 concurrent.futures 模块中的 ThreadPoolExecutor 非常适合这个场景。下面我们改造之前的函数,使其支持批量坐标输入。
import concurrent.futures
from typing import List, Tuple
def get_forecast_for_one_location(lon_lat: Tuple[float, float], location_name: str = ""):
"""包装函数,用于并发执行单个地点的请求。"""
lon, lat = lon_lat
print(f"正在获取地点 [{location_name or f'{lon},{lat}'}] 的数据...")
df = get_7day_forecast_single_point(lon, lat) # 复用方法一的函数
# 为数据框添加一个地点标识列
if df is not None:
df['location_name'] = location_name
df['longitude'] = lon
df['latitude'] = lat
return df
def batch_get_forecasts(location_list: List[tuple]):
"""
批量获取多个地点的预报数据。
location_list: 元素为 (经度, 纬度, 地点名) 或 (经度, 纬度) 的列表。
"""
all_dataframes = []
# 使用线程池,最大线程数建议不要太高,避免对API服务器造成压力或被限流
max_workers = min(5, len(location_list)) # 限制为5个并发
with concurrent.futures.ThreadPoolExecutor(max_workers=max_workers) as executor:
# 准备任务
future_to_location = {}
for loc in location_list:
if len(loc) == 3:
lon, lat, name = loc
else:
lon, lat = loc
name = ""
future = executor.submit(get_forecast_for_one_location, (lon, lat), name)
future_to_location[future] = name
# 收集结果
for future in concurrent.futures.as_completed(future_to_location):
loc_name = future_to_location[future]
try:
df = future.result()
if df is not None:
all_dataframes.append(df)
print(f"地点 [{loc_name}] 数据获取并处理完成。")
else:
print(f"警告:地点 [{loc_name}] 数据获取失败。")
except Exception as exc:
print(f'地点 [{loc_name}] 在请求过程中生成异常: {exc}')
# 合并所有数据
if all_dataframes:
final_df = pd.concat(all_dataframes, ignore_index=True)
print(f"批量获取完成!总共获取了 {len(final_df)} 条记录,涵盖 {len(all_dataframes)} 个地点。")
return final_df
else:
print("所有地点的数据获取均失败。")
return None
# 示例:获取三个城市的数据
locations = [
(116.4, 39.9, "北京"),
(121.5, 31.2, "上海"),
(113.3, 23.1, "广州")
]
combined_forecast_data = batch_get_forecasts(locations)
并发虽好,但需谨慎。过于频繁的请求可能会触发API的速率限制(Rate Limiting)。一个良好的实践是:
- 在代码中加入随机延时(
time.sleep(random.uniform(0.5, 1.5)))。 - 监控API返回的响应头,通常会有
X-RateLimit-Remaining这样的字段提示剩余请求次数。 - 对于成百上千个点的批量任务,考虑将其拆分成多个小批次,批次间有较长间隔。
4. 方法三:定时自动化任务与数据持久化
获取一次数据只是开始,真正的价值在于持续、自动地更新数据流,并将其保存下来,供后续分析和模型训练使用。这就涉及到任务调度和数据持久化两个核心环节。
任务调度方面,对于简单的个人项目或测试,可以直接使用操作系统的定时任务(如Linux的cron或Windows的任务计划程序)。但在更正式的应用中,使用Python库如 schedule 或 APScheduler 会更灵活。
数据持久化的选择很多,取决于数据量和用途:
- CSV文件: 简单直观,适合小数据量和快速查看。但增量更新和查询效率不高。
- SQLite数据库: 轻量级,无需单独服务器,适合中小型项目。支持SQL查询,管理方便。
- MySQL/PostgreSQL: 成熟的数据库,适合生产环境,支持并发访问和复杂查询。
- 时序数据库(如InfluxDB): 专门为时间序列数据优化,在存储和查询气象这类带时间戳的数据上有天然优势。
这里我展示一个结合 schedule 和 SQLite 的简单自动化示例。我们每天凌晨1点自动运行数据采集任务,并将新数据存入数据库。
import schedule
import time
import sqlite3
from datetime import datetime, timedelta
def scheduled_forecast_task():
"""定时任务执行的函数"""
print(f"[{datetime.now()}] 开始执行定时气象数据采集任务...")
# 1. 获取数据(这里以北京为例)
df = get_7day_forecast_single_point(116.4, 39.9)
if df is not None:
# 2. 数据清洗/转换(例如,确保时间列格式正确)
df['fetch_time'] = datetime.now() # 记录本次抓取的时间
# 3. 存储到SQLite数据库
conn = sqlite3.connect('weather_forecast.db')
# 如果表不存在则创建
df.to_sql('forecast_data', conn, if_exists='append', index=False)
conn.close()
print(f"[{datetime.now()}] 数据已成功保存至数据库。新增 {len(df)} 条记录。")
else:
print(f"[{datetime.now()}] 数据获取失败,本次任务跳过。")
def setup_scheduler():
"""设置调度规则"""
# 每天凌晨1点执行
schedule.every().day.at("01:00").do(scheduled_forecast_task)
# 也可以每6小时执行一次
# schedule.every(6).hours.do(scheduled_forecast_task)
print("定时任务调度器已启动。计划任务:每日01:00运行。")
print("按 Ctrl+C 退出。")
try:
while True:
schedule.run_pending()
time.sleep(60) # 每分钟检查一次是否有任务需要执行
except KeyboardInterrupt:
print("\n定时任务已停止。")
# 首次运行可以先手动执行一次,测试流程
if __name__ == "__main__":
# 测试任务函数
# scheduled_forecast_task()
# 启动调度器(正式运行时取消注释)
# setup_scheduler()
这个脚本运行后,就会成为一个常驻的后台服务。数据库中的表会随着时间积累历史预报数据,这对于后续分析预报准确性、训练预测模型非常有价值。
注意:在生产环境中,你需要考虑更多的健壮性因素,比如任务执行失败后的报警(可以通过邮件、钉钉/企业微信机器人)、日志记录、数据库连接池管理等。
5. 方法四:高级参数调优与数据解析
掌握了基础调用和自动化后,我们可以更深入地探索API的高级功能,并对获取的数据进行更有价值的解析。羲和平台提供了多达11种气象要素和260多项属性数据,如何组合和利用它们,取决于你的具体业务场景。
参数调优示例:定制化数据请求 假设我们是一个光伏电站的运维团队,我们最关心的气象要素是:
- 地表水平太阳总辐照度(GHI): 直接影响发电量。
- 气温: 影响光伏组件的工作效率。
- 云量: 是导致辐照度瞬时波动的主要因素。
- 降水量: 关系到电站的清洗计划和设备安全。
我们可以精确地请求这些变量,并可能要求更高的时间分辨率(比如15分钟间隔,如果API支持的话)。同时,我们可能只需要未来3天而非7天的数据,以获取更准确的短期预报。
def get_custom_pv_forecast(lon, lat, days=3):
"""获取光伏运维定制的气象预报数据"""
endpoint = "/weather/forecast"
# 假设API支持这些具体的变量名,需要查阅文档确认
variables_needed = "ghi,temperature,cloud_cover,precipitation"
end_date = (datetime.now() + timedelta(days=days)).strftime('%Y-%m-%d')
params = {
"location": f"{lon},{lat}",
"variables": variables_needed,
"start_date": datetime.now().strftime('%Y-%m-%d'),
"end_date": end_date,
"interval": "1h", # 请求逐小时数据,也可能是“15min”
"output_format": "json"
}
data = make_xihe_request(endpoint, params)
return data
数据解析与衍生指标计算 拿到原始数据后,直接使用往往不够。我们需要结合领域知识进行计算。例如,对于光伏电站,一个关键的衍生指标是理论发电功率估算。这可以通过一个简化的公式,利用GHI数据初步计算:
import pandas as pd
def calculate_theoretical_pv_power(weather_df, system_capacity_kw=1000, performance_ratio=0.75):
"""
根据气象数据估算理论光伏发电功率。
Args:
weather_df (DataFrame): 包含'ghi'(W/m²)和'temperature'(℃)列的数据框。
system_capacity_kw (float): 光伏系统容量,单位千瓦。
performance_ratio (float): 性能比,综合考虑了灰尘、损耗、逆变器效率等,通常0.7-0.8。
Returns:
DataFrame: 增加了'理论功率_kw'列的数据框。
"""
df = weather_df.copy()
# 标准测试条件(STC)下的辐照度是1000 W/m²
# 理论功率 = 系统容量 * (实际GHI / 1000) * 性能比 * 温度修正系数(简化版)
# 温度修正系数简化计算:1 - 0.005*(T_ambient - 25),其中25℃是STC温度
df['temperature_correction'] = 1 - 0.005 * (df['temperature'] - 25)
df['temperature_correction'] = df['temperature_correction'].clip(lower=0.9, upper=1.05) # 设定合理范围
df['理论功率_kw'] = (
system_capacity_kw *
(df['ghi'] / 1000.0) *
performance_ratio *
df['temperature_correction']
).round(2) # 保留两位小数
# 功率不可能为负,夜间GHI为0时功率也为0
df['理论功率_kw'] = df['理论功率_kw'].clip(lower=0)
return df
# 使用示例
# custom_data = get_custom_pv_forecast(116.4, 39.9)
# 假设custom_data已经转换为DataFrame df_pv
# df_pv_with_power = calculate_theoretical_pv_power(df_pv, system_capacity_kw=5000)
# print(df_pv_with_power[['time', 'ghi', 'temperature', '理论功率_kw']].head())
通过这种方式,我们就把原始的气象数据,转化为了对业务有直接指导意义的指标。你可以根据风电场、水电厂等不同场景,设计不同的衍生指标计算函数。
6. 方法五:构建简易数据服务与可视化
最后,如果我们想让团队的其他非技术人员(如项目经理、业务分析师)也能方便地查看这些数据,或者需要将数据集成到内部仪表盘中,那么构建一个简单的数据服务接口和可视化页面就很有必要。
我们可以使用轻量级的Web框架,如 Flask 或 FastAPI,快速搭建一个RESTful API,对外提供处理好的气象数据。同时,利用 ECharts、Plotly 或 Matplotlib 生成图表。
下面是一个使用 Flask 构建的极简示例,它提供一个端点,返回指定地点未来几天关键气象数据的JSON,并附带一个简单的HTML页面展示曲线图。
# app.py
from flask import Flask, jsonify, request, render_template_string
import pandas as pd
from methods import get_7day_forecast_single_point, calculate_theoretical_pv_power # 假设之前的函数放在methods.py
app = Flask(__name__)
# 一个内联的HTML模板,用于简单展示
HTML_TEMPLATE = """
<!DOCTYPE html>
<html>
<head>
<title>气象预报数据可视化</title>
<script src="https://cdn.jsdelivr.net/npm/echarts@5.4.3/dist/echarts.min.js"></script>
</head>
<body>
<h2>地点:{{ location }} 未来7天气象预报</h2>
<div id="chart" style="width: 1000px;height:600px;"></div>
<script>
var chartDom = document.getElementById('chart');
var myChart = echarts.init(chartDom);
var option = {
tooltip: { trigger: 'axis' },
legend: { data: {{ legend|safe }} },
xAxis: { type: 'category', data: {{ times|safe }} },
yAxis: [ { type: 'value', name: '温度/℃' }, { type: 'value', name: '功率/kW' } ],
series: {{ series|safe }}
};
myChart.setOption(option);
</script>
</body>
</html>
"""
@app.route('/api/forecast', methods=['GET'])
def api_get_forecast():
"""API端点:获取预报数据"""
lon = request.args.get('lon', default=116.4, type=float)
lat = request.args.get('lat', default=39.9, type=float)
df = get_7day_forecast_single_point(lon, lat)
if df is None:
return jsonify({'error': 'Failed to fetch data'}), 500
# 转换为字典列表返回
data = df.to_dict('records')
return jsonify({'location': f'{lon},{lat}', 'data': data})
@app.route('/visualize', methods=['GET'])
def visualize():
"""可视化页面"""
lon = request.args.get('lon', 116.4, type=float)
lat = request.args.get('lat', 39.9, type=float)
df = get_7day_forecast_single_point(lon, lat)
if df is None or df.empty:
return "数据获取失败", 500
# 计算理论功率(假设df中有ghi和temperature列)
if 'ghi' in df.columns and 'temperature' in df.columns:
df = calculate_theoretical_pv_power(df)
# 准备ECharts需要的数据
# 只取部分数据用于展示,避免图表过于拥挤
df_display = df.head(24*3) # 展示最近三天的每小时数据
times = df_display['time'].dt.strftime('%m-%d %H:%M').tolist()
temps = df_display['temperature'].tolist() if 'temperature' in df_display.columns else []
power = df_display['理论功率_kw'].tolist() if '理论功率_kw' in df_display.columns else []
legend = ['温度']
series = [
{'name': '温度', 'type': 'line', 'data': temps, 'yAxisIndex': 0}
]
if power:
legend.append('理论功率')
series.append({'name': '理论功率', 'type': 'line', 'data': power, 'yAxisIndex': 1})
return render_template_string(HTML_TEMPLATE,
location=f"经度{lon}, 纬度{lat}",
legend=legend,
times=times,
series=series)
if __name__ == '__main__':
app.run(debug=True, port=5000)
运行这个Flask应用后,访问 http://127.0.0.1:5000/visualize 就能看到一个简单的图表页面。访问 http://127.0.0.1:5000/api/forecast?lon=121.5&lat=31.2 则可以获取上海的原始预报数据JSON。这为前后端分离的应用提供了数据基础。
部署考虑:这个示例仅用于本地开发演示。在生产环境部署时,你需要使用 Gunicorn 或 uWSGI 这样的WSGI服务器,并配置Nginx作为反向代理,同时确保数据库连接、API密钥管理等环节的安全性。
从基础的单个请求到并发的批量处理,从定时自动化到数据深度解析,再到最终的服务化与可视化,这五种方法层层递进,基本覆盖了在实际开发中调用羲和这类气象数据API的常见场景。我最开始只用方法一,后来随着需求复杂,一步步补充了其他模块。过程中最大的体会是,错误处理和日志记录一定要从一开始就做好,否则在调试多线程或定时任务时,会非常痛苦。另外,API的响应格式偶尔可能会有细微调整,所以代码里对响应数据的解析不要写得太死,多做一些防御性判断。希望这些实战代码能帮你绕过我踩过的那些坑,快速构建起属于自己的气象数据流水线。
491



被折叠的 条评论
为什么被折叠?



