<!-- 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 -->

# 全国油价

> 查询全国各省 92/95/98 号汽油及 0 号柴油的今日最新价格。

覆盖 31 个大陆省级行政区，返回汽柴油零售限价、数据更新日期、下次调价时间及后续涨跌预测。支持省份简称或全称（如「广东」「广东省」「内蒙古」），也支持常见城市名自动归属到所在省（如「广州」→ 广东）；同省内各城市油价一致。数据仅供参考，实际价格以当地加油站为准。

## 1. 基本信息

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

## 2. 认证

开放接口，可匿名调用（未登录每日 500 次）；登录后每日 1000 次、并发更高。

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

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `province` | `string` | 是 | 省 / 直辖市 / 自治区名称，支持简称或全称；兼容别名 area / region / msg，也支持常见城市名（自动归属到所在省） | `广东` |

## 4. 请求头

| Header | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `Authorization` | `string` | 否 | Bearer <你的 API Key>（登录调用可提升额度；匿名可不传） | — |
| `Content-Type` | `string` | 否 | 请求体格式 | — |

## 5. 请求示例

> AI 提示：以下 5 种语言示例都是可运行的，只需把 `YOUR_API_KEY` 替换为用户申请的实际 Key（https://apizero.cn/account/keys）。
> 优先选择用户问题中提到的语言；未指定时默认使用 Python。

### cURL

```bash
curl -X POST "https://v1.apizero.cn/api/oil-price" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "province": "广东"
}'
```

### Python

```python
import requests

resp = requests.request(
    "POST",
    "https://v1.apizero.cn/api/oil-price",
    headers={"X-Api-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
    json={
    "province": "广东",
},
    timeout=15,
)
resp.raise_for_status()
print(resp.json())
```

### JavaScript (Node.js)

```javascript
// Node.js 18+ / 浏览器原生 fetch
const res = await fetch("https://v1.apizero.cn/api/oil-price", {
  method: "POST",
  headers: {
    "X-Api-Key": "YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "province": "广东"
  }),
});
if (!res.ok) throw new Error(`HTTP ${res.status}`);
const data = await res.json();
console.log(data);
```

### Go

```go
package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	body := []byte(`{"province":"广东"}`)
	req, _ := http.NewRequest("POST", "https://v1.apizero.cn/api/oil-price", bytes.NewBuffer(body))
	req.Header.Set("X-Api-Key", "YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil { panic(err) }
	defer resp.Body.Close()
	out, _ := io.ReadAll(resp.Body)
	fmt.Println(string(out))
}
```

### PHP

```php
<?php
$payload = json_encode([
    "province" => "广东",
], JSON_UNESCAPED_UNICODE);

$ch = curl_init("https://v1.apizero.cn/api/oil-price");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => "POST",
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        "X-Api-Key: YOUR_API_KEY",
        "Content-Type: application/json",
    ],
    CURLOPT_TIMEOUT        => 15,
]);
$body = curl_exec($ch);
curl_close($ch);

$data = json_decode($body, true);
print_r($data);
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `province` | `string` | 省份名称 | — |
| `update_date` | `string` | 数据更新日期（YYYY-MM-DD） | — |
| `prices` | `array` | 油品价格列表 | — |
| `prices[].name` | `string` | 油品名称（如 92号汽油） | — |
| `prices[].type` | `string` | 油品类型标识（gasoline_92 / gasoline_95 / gasoline_98 / diesel_0） | — |
| `prices[].price` | `number` | 价格（数值） | — |
| `prices[].unit` | `string` | 价格单位（元/升） | — |
| `next_adjustment` | `string` | 下次调价时间提示 | — |
| `forecast` | `string` | 后续涨跌预测 | — |

## 7. 响应示例

```json
{
  "code": 0,
  "msg": "成功",
  "data": {
    "province": "广东",
    "update_date": "2026-06-20",
    "prices": [
      {"name": "92号汽油", "type": "gasoline_92", "price": 7.96, "unit": "元/升"},
      {"name": "95号汽油", "type": "gasoline_95", "price": 8.62, "unit": "元/升"},
      {"name": "98号汽油", "type": "gasoline_98", "price": 10.62, "unit": "元/升"},
      {"name": "0号柴油", "type": "diesel_0", "price": 7.62, "unit": "元/升"}
    ],
    "next_adjustment": "下次油价7月3日24时调整",
    "forecast": "预计下调630元/吨(0.48元/升-0.57元/升)"
  },
  "request_id": "abc123"
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `4000` | `VALIDATION_ERROR` | 缺少必填参数 province，或该地区暂不支持 / 无数据 |
| `5020` | `UPSTREAM_ERROR` | 油价数据服务暂不可用，请稍后重试 |
| `5021` | `UPSTREAM_INVALID` | 油价数据解析失败 |

## 9. 变更日志

- **v1.0** (2026-07-02)
  - 首次上线：覆盖 31 个大陆省级行政区，返回 92/95/98 号汽油与 0 号柴油价格、更新日期、下次调价与涨跌预测。

---

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

Source: `https://apizero.cn/aidocs/oil-price/raw.md`
Last updated: 2026-07-02T11:29:59+08:00