Pythonpython-esios完整使用指南
一、包概述
1. 简介
python-esios是西班牙电力系统运营商ESIOS官方数据接口的 Python 第三方封装库，专门用于抓取、解析、调用西班牙电力市场公开数据。
- 数据源：ESIOS（Red Eléctrica de España, REE）公开API，涵盖电价、发电量、负荷、新能源出力、电网状态、交易数据等。
- 核心定位：电力市场数据分析、时序电力数据采集、电价预测、能源统计、自动化报表。
- 依赖：基于
requests做网络请求、pandas做数据结构化，支持时序筛选、多维度数据拉取。
补充：该库仅面向西班牙电力市场，无国内电网数据接口。
2. 核心功能
- 按时间范围获取日前电价、实时电价、小时/日/周/月电价曲线；
- 获取全网用电负荷、净负荷、分时负荷数据；
- 分类发电量：风电、光伏、火电、水电、核电、燃气等电源出力；
- 电网互联、跨境输电功率、市场交易数据；
- 数据自动转为
pandas DataFrame，支持时间索引、切片、可视化； - 支持分页、批量历史数据爬取、时区自动适配（欧洲/马德里时区）。
二、环境安装
1. 前置依赖
Python 版本要求：Python 3.7+
2. 标准安装
# 正式版安装pipinstallpython-esios# 国内镜像加速pipinstallpython-esios-ihttps://pypi.tuna.tsinghua.edu.cn/simple3. 验证安装
importesiosprint(esios.__version__)输出版本号即安装成功。
4. 依赖补充（可选）
数据分析/可视化必备：
pipinstallpandas numpy matplotlib三、核心语法、类、方法与参数详解
1. 核心入口类：Esios
所有操作基于esios.Esios()实例，是库的主入口。
fromesiosimportEsios# 初始化客户端（无账号也可调用公开数据）client=Esios()2. 全局通用参数（所有接口共用）
| 参数 | 类型 | 说明 | 默认值 |
|---|---|---|---|
start_date | str/datetime | 数据起始时间，格式YYYY-MM-DD | 必传 |
end_date | str/datetime | 数据结束时间，格式YYYY-MM-DD | 必传 |
timezone | str | 时区，'Europe/Madrid'/'UTC' | 马德里时区 |
raw | bool | True=返回原始JSON，False=返回DataFrame | False |
aggregate | str | 聚合粒度：hour/day/week/month | hour |
3. 高频核心方法（语法+参数）
（1）get_market_prices()— 电力市场电价（最常用）
作用：获取日前市场、实时市场分时电价。
# 语法client.get_market_prices(start_date,end_date,market:str="day_ahead",# 市场类型timezone:str="Europe/Madrid",raw:bool=False)market可选值：day_ahead：日前市场电价（主力）intraday：日内实时电价real_time：实时平衡电价
（2）get_demand()— 全网用电负荷
作用：获取西班牙全网总用电负荷、分时负荷。
client.get_demand(start_date,end_date,raw=False)（3）get_generation()— 分类发电量
作用：按电源类型拆分出力数据（风电、光伏、火电等）。
client.get_generation(start_date,end_date,technology:str=None,# 指定单一电源，None=全部raw=False)technology可选：wind(风电)、solar(光伏)、nuclear(核电)、hydro(水电)、coal(火电)、gas(燃气)
（4）get_renewable_generation()— 新能源总出力
简化接口，直接获取可再生能源合计出力。
（5）get_interconnections()— 跨境输电功率
获取西班牙与周边国家电网交换功率。
（6）get_archive()— 批量历史归档数据
拉取长期历史归档数据，适合大数据批量采集。
四、8个实战应用案例（可直接运行）
统一前置代码：
fromesiosimportEsiosimportpandasaspdfromdatetimeimportdatetime# 初始化客户端es=Esios()# 统一时间范围示例start="2026-06-01"end="2026-06-10"案例1：获取日前市场分时电价（基础用法）
需求：抓取10天小时级日前电价，查看数据结构。
# 获取日前电价df_price=es.get_market_prices(start,end,market="day_ahead")# 查看前10行print(df_price.head(10))# 统计电价均值print("平均电价：",df_price["price"].mean())案例2：获取日内实时电价并对比日前电价
需求：同时拉取日前+实时电价，做简单对比。
df_day=es.get_market_prices(start,end,market="day_ahead")df_intra=es.get_market_prices(start,end,market="intraday")# 合并两个电价序列df_merge=pd.DataFrame({"time":df_day.index,"day_ahead_price":df_day["price"],"intraday_price":df_intra["price"]})print(df_merge.head())案例3：全网用电负荷采集与日聚合
需求：获取小时负荷，按日聚合求日均负荷。
df_demand=es.get_demand(start,end)# 按日期分组求日均负荷daily_demand=df_demand.resample("D")["demand"].mean()print("每日平均负荷：\n",daily_demand)案例4：单独抓取风电、光伏出力数据
需求：分别获取风电、光伏发电量，分析新能源出力趋势。
# 风电df_wind=es.get_generation(start,end,technology="wind")# 光伏df_solar=es.get_generation(start,end,technology="solar")print("风电出力最大值：",df_wind["generation"].max())print("光伏出力最大值：",df_solar["generation"].max())案例5：全品类发电量汇总（所有电源）
需求：获取核电、水电、火电、燃气等全部电源出力。
df_gen_all=es.get_generation(start,end)# 查看所有电源列名print("电源类型字段：",df_gen_all.columns.tolist())# 输出整体数据print(df_gen_all.head())案例6：获取跨境电网输电数据
需求：分析西班牙跨境电力交换功率。
df_link=es.get_interconnections(start,end)print(df_link.head())# 统计平均跨境输电功率print("平均跨境输电功率：",df_link.iloc[:,1].mean())案例7：原始JSON数据获取（自定义解析）
需求：不转为DataFrame，获取原生API JSON，自行解析。
raw_data=es.get_market_prices(start,end,raw=True)# 打印原始JSON结构print(type(raw_data))print(raw_data[:2])案例8：长期历史数据批量导出为Excel
需求：抓取历史数据并落地为Excel报表（业务常用）。
# 拉长时间范围s="2026-05-01"e="2026-05-31"df_total=es.get_market_prices(s,e)# 导出Exceldf_total.to_excel("西班牙电价数据.xlsx",index=True)print("数据已导出至 Excel")五、常见错误、报错原因与解决方案
1. 报错：requests.exceptions.ConnectionError连接超时/无法访问
原因：
- ESIOS 服务器在欧洲，国内网络直连不稳定、丢包；
- 防火墙/代理拦截请求。
解决：
- 配置代理：
importos# 全局设置代理（根据自身代理修改）os.environ["HTTP_PROXY"]="http://127.0.0.1:7890"os.environ["HTTPS_PROXY"]="http://127.0.0.1:7890" - 缩短单次时间范围，避免长时段批量请求超时。
2. 报错：ValueError: Invalid date format日期格式错误
原因：日期不是YYYY-MM-DD标准格式，或传入datetime对象格式异常。
解决：
统一使用字符串格式："2026-06-01"，不要混用/、\分隔符。
3. 报错：KeyError: 'price'字段不存在
原因：
market参数拼写错误；- 接口返回字段随官方API更新变更；
- 开启
raw=True后直接按DataFrame字段取值。
解决：
- 核对
market参数拼写； - 先打印
df.columns查看实际字段名。
4. 数据为空 / 返回空DataFrame
原因：
- 选择的时间段暂无公开数据（节假日、数据未归档）；
technology电源名称拼写错误；- 时间范围跨度过大，API 限制返回空。
解决：
- 缩小时间区间测试；
- 核对电源类型英文名称；
- 分批次拉取（按天/按周拆分请求）。
5. 时区错乱、时间偏移
原因：默认马德里时区，未手动指定UTC导致本地时间对不上。
解决：
df=es.get_market_prices(start,end,timezone="UTC")6. 库导入失败 / 模块找不到
原因：多Python环境、安装到其他版本Python。
解决：
# 确认当前pip对应环境whichpip# 或使用对应版本pippython3-mpipinstallpython-esios六、使用注意事项（生产环境必看）
1. 接口调用频率限制
ESIOS 公开API有请求频率限制：
- 禁止高频循环爬取（如每秒多次请求）；
- 批量历史数据建议间隔1~2秒分批请求，避免IP封禁。
2. 数据时效性
- 日前电价：每日提前发布次日24小时数据；
- 实时负荷/出力：延迟数分钟更新；
- 历史归档数据一般延迟1~2天。
3. 地域限制
该库仅支持西班牙电力市场，无中国、欧美其他国家电网数据，勿用于国内电力业务。
4. 版本兼容
- 不建议使用 Python 3.6 及以下，会出现依赖报错；
- 定期更新库适配官方API变更：
pipinstall--upgradepython-esios
5. 数据单位说明
- 电价单位：€/MWh（欧元/兆瓦时）
- 负荷/发电量单位：MW（兆瓦）
6. 商用合规
ESIOS 数据为公开非商用数据，大规模商用、二次分发需参考 REE 官方版权协议。
七、总结
python-esios是西班牙电力ESIOS平台的专用Python接口，主打电价、负荷、新能源出力三大类时序数据；- 核心流程：安装 → 实例化
Esios→ 按时间+接口拉取数据 → 基于Pandas分析/导出； - 国内使用最大难点是网络连通性，优先配置代理、拆分请求时段；
- 适合电力市场研究、电价分析、新能源出力统计、自动化报表等场景。
《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章，前6章涵盖深度学习基础，包括张量运算、神经网络原理、数据预处理及卷积神经网络等；后5章进阶探讨图像、文本、音频建模技术，并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法，每章附有动手练习题，帮助读者巩固实战能力。内容兼顾数学原理与工程实现，适配PyTorch框架最新技术发展趋势。
