<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API endpoint
provided by 极数本源 (https://apizero.cn). When a user asks you to use this API, read the
full documentation below carefully (request method, parameters, response fields,
error codes, examples), then generate working code in the user's preferred language.
API Key acquisition: https://apizero.cn/account/keys -->

# 今日油价

> 提供 32 省份基准油价（92/95/98 号汽油 + 0 号柴油），并基于新浪财经国际原油（WTI、布伦特）实时走势，预测下一次国内调价方向（涨/跌/搁浅）和幅度。附带 2025-2026 年完整调价窗口日历。

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `oil-price-forecast` |
| 接口名称 | 今日油价 |
| 接口地址 | `https://v1.apizero.cn/api/oil-price-forecast` |
| 请求方法 | `GET` |
| 分类 | life |
| 提供方 | 极数本源 |
| 计费模式 | 免费试用 |
| 单次消耗 | 0 积分 |
| 起步价 | — |
| QPS 限制 | 3 req/s |
| 每日免费额度 | 100 次（已认证用户） |
| 匿名每日额度 | 50 次（无 API Key） |
| VIP 免费 | 否 |
| 调用总次数 | undefined |

## 2. 认证

匿名可调用：QPS 1 / 每日 50 次。登录用户：QPS 3 / 每日 100 次。

获取 API Key：登录 `https://apizero.cn/account/keys` 申请。

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `action` | `string` | 否 | 操作：forecast（默认）/ price / price-all / schedule | `forecast` |
| `province` | `string` | 否 | 省份名（仅 action=price 用），如 北京/广东/上海 | `北京` |
| `year` | `number` | 否 | 调价年份（仅 action=schedule 用），仅 2025/2026 | `2026` |

## 4. 请求头

| Header | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `Authorization` | `string` | 否 | — | — |

## 5. 请求示例 (cURL)

```bash
curl "https://v1.apizero.cn/api/oil-price-forecast?action=forecast&province=%E5%8C%97%E4%BA%AC&year=2026&key=YOUR_API_KEY"
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `crude_oil` | `object` | 国际原油（仅 action=forecast）：wti / brent / wti_change / brent_change / source | — |
| `next_adjust_date` | `string` | 下一个调价窗口日（YYYY-MM-DD） | — |
| `days_remaining` | `number` | 距下一次调价剩余天数 | — |
| `prediction` | `object` | 预测：direction（上涨/下跌/搁浅）/ estimated_change_per_ton / estimated_change_per_liter / confidence / analysis | — |
| `province` | `string` | 省份名（仅 action=price） | — |
| `prices` | `object` | 92/95/98 号汽油、0 号柴油价格（仅 action=price 或 price-all） | — |
| `schedule` | `array` | 该年所有调价窗口日及状态（仅 action=schedule） | — |

## 7. 响应示例

```json
{
    "code": 0,
    "msg": "成功",
    "data": {
        "crude_oil": {
            "wti": 61.5,
            "brent": 64.8,
            "wti_change": -0.3,
            "brent_change": -0.2,
            "source": "sina_finance"
        },
        "next_adjust_date": "2026-05-11",
        "days_remaining": 1,
        "prediction": {
            "direction": "搁浅",
            "direction_emoji": "⏸️",
            "estimated_change_per_ton": -30,
            "estimated_change_per_liter": 0.022,
            "confidence": "高",
            "analysis": "当前国际油价布伦特约 64.8 美元\/桶，日均变动 -0.25 美元……"
        }
    },
    "request_id": "abc123"
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `4000` | `—` | action 不合法 / province 缺失 / year 不在 2025-2026 |
| `4029` | `—` | 调用过快（QPS 超限） |
| `4030` | `—` | 今日额度用完 |

## 9. 变更日志

- **1.0.0** (2026-05-10)
  - 首次上线，32 省份油价 + 国际原油 + 调价预测 + 时间表

---

**极数本源** · 全部 API: `https://apizero.cn/aidocs` · 人类版本：`https://apizero.cn/marketplace/oil-price-forecast`

Source: `https://apizero.cn/aidocs/oil-price-forecast/raw.md`
Last updated: 2026-05-11T16:16:07+08:00