1. 适用场景油价是高频民生数据各类出行、物流、金融应用中常需要展示最新油价及调价预测。今日油价API可提供以下核心数据省份基准油价92/95/98号汽油及0号柴油覆盖32个省份。国际原油实时行情WTI、布伦特用量说明及日变动数据源自新浪财经。下一轮调价预测根据国际原油变化率预估国内成品油调价方向涨/跌/搁浅及幅度元/升或元/吨。调价窗口日历2025-2026年完整调价日期。典型应用包括车主加油提醒App、物流维护复杂度计算器、财经资讯插件、企业内部油价监控系统等。2. 接口能力边界在集成前需明确以下能力边界QPS限制3次/秒适合低并发个人或小团队项目大规模调用需注意限流。数据更新频率国际原油数据实时更新依赖新浪财经国内成品油用量说明随官方调价变动通常每10个工作日调整一次。预测结果基于当前国际油价走势不代表最终结果。省份支持仅支持素材中列出的32个省份偏远地区可能缺失。历史数据接口不提供历史油价记录仅返回当前最新数据。3. 请求参数与鉴权3.1 请求地址GET https://v1.apizero.cn/api/oil-price-forecast3.2 Query参数参数名是否必须类型说明示例值action否string操作类型forecast默认调价预测、price指定省份油价、price-all全部省份油价、schedule调价日历forecastprovince否string省份名仅当actionprice时使用如北京、广东、上海北京year否number调价年份仅当actionschedule时使用支持2025、202620263.3 Header参数参数名是否必须类型说明Authorization否string从Apizero平台获取的API Key建议放在HTTP Header中格式为Bearer YOUR_API_KEY或自定义方式注根据官方文档密钥也可通过URL参数传递但为安全建议使用Header。具体鉴权方式以文档页为准。4. curl请求示例以下示例获取默认的调价预测数据无需省份参数curl -sS \ -X GET \ -H Authorization: Bearer YOUR_API_KEY \ https://v1.apizero.cn/api/oil-price-forecast?actionforecast获取指定省份如广东的当前油价curl -sS \ -X GET \ -H Authorization: Bearer YOUR_API_KEY \ https://v1.apizero.cn/api/oil-price-forecast?actionpriceprovince广东获取2026年调价窗口日历curl -sS \ -X GET \ -H Authorization: Bearer YOUR_API_KEY \ https://v1.apizero.cn/api/oil-price-forecast?actionscheduleyear2026所有示例中请将YOUR_API_KEY替换为实际密钥。返回格式统一为JSON数组第一个元素包含业务数据。5. 响应数据结构解读接口返回一个JSON数组每个元素代表一种响应状态。默认成功返回如下结构以actionforecast为例[ { content_type: application/json, description: 成功, example: { code: 0, 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 } }, msg: 成功, request_id: abc123 }, status: 200 } ]5.1 顶层字段说明字段名类型说明content_typestring响应内容类型通常为application/jsondescriptionstring状态描述成功时成功错误时参数错误等exampleobject实际业务数据体包含code、msg、data、request_idstatusstringHTTP状态码字符串如2005.2 example对象字段字段名类型说明codenumber业务码0表示成功非0表示错误msgstring业务消息成功成功错误时描述原因request_idstring请求唯一标识可用于日志追踪dataobject数据主体根据action不同结构不同5.3 data对象actionforecast字段名类型说明crude_oilobject国际原油数据包含brent、brent_change、wti、wti_change、sourcedays_remainingnumber距离下一调价窗口的天数next_adjust_datestring下一调价日期格式yyyy-MM-ddpredictionobject调价预测详情crude_oil对象字段类型说明brentnumber布伦特原油用量说明美元/桶brent_changenumber布伦特日变动值wtinumberWTI原油用量说明美元/桶wti_changenumberWTI日变动值sourcestring数据来源sina_financeprediction对象字段类型说明analysisstring调价分析描述文字含数据依据confidencestring预测置信度高、中、低directionstring调价方向涨、跌、搁浅direction_emojistring对应emoji用于展示estimated_change_per_liternumber每升预估变动金额元正数涨、负数跌estimated_change_per_tonnumber每吨预估变动金额元正数涨、负数跌其它actionprice、price-all、schedule的data结构不同本文不再展开请参考官方文档。6. 常见错误处理6.1 HTTP层面错误状态码含义可能原因处理建议400Bad Request参数缺失或格式错误检查action、province、year参数合法性401UnauthorizedAPI Key无效或未传递确认鉴权方式及密钥有效性404Not Found接口地址错误检查URL路径429Too Many Requests超出QPS限制增加请求间隔或采用限流策略5xxServer Error服务端临时故障指数退避重试6.2 业务错误码响应中example.code非0时example.msg会给出具体错误描述。常见业务错误code: 1001省份参数无效如不支持的省份名code: 1002年份参数超出范围非2025/2026code: 1003接口内部数据获取失败如新浪财经源异常建议始终校验code字段根据msg或错误类型做相应处理。7. 工程化注意事项7.1 缓存策略国际原油数据实时性高建议缓存时间不超过1分钟。国内省份油价在调价窗口期外几乎不变可缓存至下一调价日参考next_adjust_date。调价日历数据为静态可缓存一天或更久。7.2 限流与重试QPS上限3若并发需求较高可考虑使用任务队列或代理分组调用。建议在客户端实现指数退避重试如5xx错误但需注意不能加重服务端压力。7.3 数据时效性预测结果基于当前国际油价仅在调价窗口临近时如days_remaining较小参考价值较高。实际调价结果以国家发改委官方通告为准API预测仅供参考不构成投资决策依据。7.4 安全合规API Key切勿硬编码在客户端代码或公开仓库中。建议使用环境变量或密钥管理服务。若需在前端直接调用建议通过后端代理转发避免密钥泄露。使用HTTPS传输确保数据加密。8. 参考文档接口文档页https://apizero.cn/aidocs/oil-price-forecast原始Markdown文档https://apizero.cn/aidocs/oil-price-forecast/raw.md本文档基于2026-05-10发布的API事实卡编写参数与行为以官方最新文档为准。