适用场景与接口能力边界今日油价 API 为开发者提供中国大陆 32 个省份的 92/95/98 号汽油及 0 号柴油基准用量说明同时基于新浪财经的 WTI 与布伦特实时走势预测下一次国内成品油调价的方向上涨/下跌/搁浅和幅度。此外还附带 2025–2026 年完整的调价窗口日历。能力边界仅覆盖中国内地 32 省份不含港澳台省份名需使用标准汉字如“北京”、“广东”。油价数据来源于官方基准价实际加油站零售价可能存在小幅度浮动。调价预测基于国际原油变化率模型不构成投资建议仅供开发者在产品中展示辅助信息。接口 QPS 限制为 3 次/秒适合中小规模应用高并发场景需搭配缓存或限流。适用行业包括导航类 App 的油价面板、金融信息聚合平台、个人记账工具或智能家居屏显等场景。请求参数详解接口采用 GET 方法基础地址为https://v1.apizero.cn/api/oil-price-forecastQuery 参数参数名必填类型说明示例action否string操作类型forecast默认、price、price-all、scheduleforecastprovince否string省份名仅当actionprice时有效北京year否number调价年份仅当actionschedule时有效可取值 2025 或 20262026action 四种模式说明forecast返回当前国际原油数据、距下次调价剩余天数、下次调价日期以及预测方向、幅度与分析文本。price需同时提供province返回该省份各标号油价。price-all返回全部 32 省份的油价。schedule可选提供year返回对应年份的调价窗口日期列表。Header 鉴权参数接口要求通过请求头传递 API 密钥。根据最新文档支持两种方式之一X-API-Key:你的API密钥Authorization:你的API密钥实际使用时请以官网文档为准这里建议统一采用X-API-Key方式与多数 curl 示例兼容。密钥需向服务提供方申请本文不涉及申请流程。可复制的请求示例curl 示例获取当前调价预测curl -sS \ -X GET \ -H X-API-Key: YOUR_API_KEY_HERE \ https://v1.apizero.cn/api/oil-price-forecast?actionforecast将YOUR_API_KEY_HERE替换为实际密钥即可得到 JSON 响应。获取省份油价以北京为例curl -sS \ -X GET \ -H X-API-Key: YOUR_API_KEY_HERE \ https://v1.apizero.cn/api/oil-price-forecast?actionpriceprovince北京Python 3 示例使用 requests 库对于工程化集成推荐使用 Python 编写稳定的调用函数import requests import json def get_oil_forecast(api_key, actionforecast, provinceNone, yearNone): url https://v1.apizero.cn/api/oil-price-forecast headers {X-API-Key: api_key} params {action: action} if province: params[province] province if year: params[year] year try: resp requests.get(url, headersheaders, paramsparams, timeout10) resp.raise_for_status() return resp.json() except requests.exceptions.RequestException as e: print(f请求失败: {e}) return None if __name__ __main__: # 替换为真实密钥 key YOUR_API_KEY_HERE result get_oil_forecast(key, actionforecast) print(json.dumps(result, indent2, ensure_asciiFalse))响应字段逐层解读成功返回的 HTTP 状态码为 200Content-Type 为application/json。顶层结构如下{ code: 0, data: { ... }, msg: 成功, request_id: abc123 }字段名类型说明codeint业务状态码0 表示成功非 0 请参考 msgdataobject具体业务数据结构因 action 不同而异msgstring状态描述request_idstring请求唯一标识便于排查问题时提供给支持actionforecast 时 data 结构{ crude_oil: { brent: 64.8, brent_change: -0.2, source: sina_finance, wti: 61.5, wti_change: -0.3 }, days_remaining: 1, next_adjust_date: 2026-05-11, prediction: { analysis: 当前国际油价布伦特约 64.8 美元/桶日均变动 -0.25 美元……, confidence: 高, direction: 搁浅, direction_emoji: ⏸️, estimated_change_per_liter: 0.022, estimated_change_per_ton: -30 } }crude_oil国际原油实时数据来源标注为新浪财经。brent_change和wti_change为当日变动值单位美元/桶。days_remaining距下次调价窗口开启的剩余天数。next_adjust_date下次调价日期YYYY-MM-DD 格式。prediction核心预测信息。direction涨、跌 或 搁浅。confidence低/中/高代表模型置信度。estimated_change_per_liter每升预估变动金额单位元。estimated_change_per_ton每吨预估变动金额单位元。analysis文本分析摘要可用于直接展示。actionprice 时 data 结构当请求单个省份时data 中包含类似如下字段{ province: 北京, prices: { 92: 7.58, 95: 8.06, 98: 9.56, 0: 7.28 }, update_time: 2026-05-10 08:00:00 }其中92、95、98对应汽油标号0为 0 号柴油单位元/升。actionprice-all 时 data 结构返回一个数组每个元素包含省份名与油价对象结构与单个 price 类似不再赘述。actionschedule 时 data 结构{ year: 2026, window_dates: [ 2026-01-15, 2026-01-29, ... ] }window_dates为该年所有调价窗口的日期列表通常每两周一次。常见错误排查HTTP 状态码code可能原因解决方式401-API 密钥缺失或无效检查请求头中X-API-Key是否正确传递400-参数不合法或缺失必要参数确认action取值是否在指定枚举内province是否正确2001001省份名未找到检查省份汉字是否完整如“内蒙古”而非“内蒙”2001002年份超出支持范围schedule模式仅支持 2025–2026注意业务错误时code字段非 0msg会描述具体原因应在逻辑中判断code为 0 才视为成功。工程化注意事项QPS 控制与缓存策略接口上限为 3 QPS若单个用户数超过 300 人建议在服务端做二级缓存如 Redis油价数据可缓存 10–30 分钟调价预测可缓存 30–60 分钟避免频繁请求。省份名规范仅支持标准称谓如“广西”、“西藏”、“辽宁”。建议在前端使用预先维护的下拉列表或地图选择器避免用户手写错误。错误重试对于网络超时设置 5–10 秒超时或 5xx 服务器错误可采用指数退避重试最多 3 次。本地化与多线程安全若用 Pythonrequests线程不安全可使用Session对象或在线程池中单独创建 Session。响应体大小price-all返回所有省份油价数据量较大约 3–5 KB注意前端解析性能。键名稳定性油价键为数字字符串如92、95、98、0注意类型转换。备用数据源该接口数据依赖新浪财经与官方调价日历如遇源站不可用接口可能返回 502 或空数据建议设计降级方案展示上次缓存数据。参考文档官方接口文档与原始 Markdown 手册今日油价 API 文档原始文档Markdown以上链接仅用于查阅最新参数与变更日志开发者应定期关注更新。