# 油价提前查询 API：配合免费的调价日历，只在调价日蹲新价

发改委成品油调价是有节奏的：一年大约二十四次，每次在调价日零点切换。做油品定价、运费报价、结算对账的系统，最难处理的不是价格本身，而是「零点切换那一刻」——零点前要用旧价，零点后要用新价，而很多系统在零点附近拿到的还是旧数据。


- ``api.xujian.tech``
- `V`：``xujian_cq``

`oilprice.advance` 的处理方式很直接：按**「当前时间 + 2 小时」**所在的日期取生效批次。也就是说，晚上 22 点之后调用，拿到的是**还没生效的新批次**，返回值里的 `advance` 会明确告诉你这一点（true = 即将生效的新价格，false = 当前生效价格）。接口是 **按年付费 360 元/年** 的套餐，需要先在后台完成授权。

## 接口速览

| 关键事实 | 说明 |
|------|------|
| 接口地址 | `https://api.xujian.tech/openapi/oilprice/advance` |
| 接口编码 | `oilprice.advance` |
| 请求方式 | GET（参数放 Query 名） |
| 鉴权方式 | 请求头 `X-API-Key`，不做签名、时间戳或加密 |
| 查询参数 | `province`、city`、`district`，**全部可选**，不传返回全部地区 |
| 返回核心字段 | `effectiveDate`、`advance`、`total`、`list[]` |
| 计费方式 | **按年付费，360.00 元/年**（不同于其他接口的按次计费） |
| 授权要求 | **需后台按年授权**；未授权或授权过期返回「接口未授权或授权已过期」 |
| 单次耗时 | 本地查询，`costMs` 常在个位数毫秒 |
| 是否扣余额 | 套餐内不扣费，`balance` 交易前后一致 |

## 一、为什么是「当前时间 + 2 小时」

| 调用时间 | 取到的批次 | `advance` | 说明 |
|------|----------|-----------|------|
| 调价日前一天 22:00 之后 | 次日零点生效的新批次 | `true` | 这就是要提前拿到的新价 |
| 调价日当天任意时间 | 当天已生效批次 | `false` | 与实时接口结果一致 |
| 非调价日 | 最近一批已生效价格 | `false` | 没有新价可提前给 |

这个 +2 小时的设计把「跨零点」的判断封装在服务端：调用方不用自己算时区、不用判断今天是否调价日，只需要看 `advance` 字段。

> **配套的免费日历**：还有个免费的调价周期接口，默认返回当年全部的调价生效日期（约 24 次/年）。用它来安排定时任务，**只在调价日前一天晚上跑一次 `oilprice.advance`**，既不会漏也不会白跑。

## 二、请求参数

### 2.1 请求头

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| `X-API-Key` | String | 是 | 开发者 API 名；缺失返回「缺少请求头 X-API-Key」 |

### 2.2 查询参数（全部可选）

| 参数名 | 必填 | 类型 | 示例 | 说明 |
|--------|------|------|------|------|
| `province` | 否 | String | 重庆市 | 省名称或 6 位 adcode；**不传返回全部地区** |

> 这里还有 `city`、`district`，用于进一步收窄到地市 / 区县，取值同样是名称或 6 位 adcode。三者都不传时返回全部地区。

## 三、返回字段

### 3.1 顶层结构

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | int | `0` 成功，非 0 失败（统一为 `500`） |
| `msg` | String | 成功为 `success`，失败为具体原因 |
| `data` | Object | 业务数据，失败时为 `null` |

### 3.2 业务字段

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `effectiveDate` | String | 2026-09-25 | **返回价格批次的生效开始时间** `yyyy-MM-dd` |
| `advance` | boolean | true | `true` = 尚未生效的新价格；`false` = 当前生效价格 |
| `total` | int | 1 | 返回条数 |
| `list` | Array | […] | 价格明细，字段与全量接口完全一致 |
| `apiCode` / `apiName` / `chargeType` / `balance` / `costMs` | — | — | 公共字段 |

`list[]` 明细字段（与全量接口一致）：

| 字段 | 类型 | 说明 |
|------|------|------|
| `effectiveDate` | String | 价格生效日期 `yyyy-MM-dd` |
| `province` / `provinceCode` | String | 省名称与 6 位 adcode |
| `city` / `cityCode` | String | 地市名称与代码；`null` 表示全省统一价 |
| `district` / `districtCode` | String | 区县名称与代码；`null` 表示全市统一价 |
| `priceDiesel0` | BigDecimal | 0#柴油价格（元） |
| `priceDiesel10` | BigDecimal | -10#柴油价格（元） |
| `priceDiesel35` | BigDecimal | -35#柴油价格（元） |
| `priceGas92` | BigDecimal | 92#汽油价格（元） |
| `priceGas95` | BigDecimal | 95#汽油价格（元） |
| `priceGas98` | BigDecimal | 98#汽油价格（元） |
| `dataUpdateTime` | String | 数据更新时间 `yyyy-MM-dd HH:mm:ss` |

## 四、调用示例

### 4.1 curl

```bash
# 全部地区
curl -s "https://api.xujian.tech/openapi/oilprice/advance" \
  -H "X-API-Key: 你的APIKey"

# 只看某个省
curl -s "https://api.xujian.tech/openapi/oilprice/advance?province=%E9%87%8D%E5%BA%86%E5%B8%82" \
  -H "X-API-Key: 你的APIKey"
```

### 4.2 成功响应（查到即将生效的新价格）

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "effectiveDate": "2026-09-25",
    "advance": true,
    "total": 1,
    "list": [
      {
        "effectiveDate": "2026-09-25",
        "provinceCode": "500000",
        "province": "重庆市",
        "cityCode": null,
        "city": null,
        "districtCode": null,
        "district": null,
        "priceDiesel0": 7.41,
        "priceDiesel10": 7.86,
        "priceDiesel35": 8.20,
        "priceGas92": 8.02,
        "priceGas95": 8.48,
        "priceGas98": 9.55,
        "dataUpdateTime": "2026-09-24 22:05:00"
      }
    ],
    "apiCode": "oilprice.advance",
    "apiName": "提前查询发改委价格",
    "chargeType": "YEARLY",
    "balance": 100.0000,
    "costMs": 8
  }
}
```

### 4.3 无新价时返回当前生效价格（advance = false）

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "effectiveDate": "2026-09-11",
    "advance": false,
    "total": 1,
    "list": [
      {
        "effectiveDate": "2026-09-11",
        "provinceCode": "500000",
        "province": "重庆市",
        "cityCode": null,
        "city": null,
        "districtCode": null,
        "district": null,
        "priceDiesel0": 7.28,
        "priceDiesel10": 7.72,
        "priceDiesel35": 8.05,
        "priceGas92": 7.86,
        "priceGas95": 8.31,
        "priceGas98": 9.36,
        "dataUpdateTime": "2026-09-11 09:00:00"
      }
    ],
    "apiCode": "oilprice.advance",
    "apiName": "提前查询发改委价格",
    "chargeType": "YEARLY",
    "balance": 100.0000,
    "costMs": 7
  }
}
```

### 4.4 Python：调价日前夜蹲新价

```python
import requests
from datetime import datetime

ADVANCE_URL = "https://api.xujian.tech/openapi/oilprice/advance"
CYCLE_URL = "https://api.xujian.tech/openapi/oilprice/cycle"   # 免费


def is_adjust_day(today: str) -> bool:
    """用免费的调价日历判断今天是不是调价日"""
    resp = requests.get(CYCLE_URL, headers={"X-API-Key": API_KEY}, timeout=10)
    result = resp.json()
    if result.get("code") != 0:
        return False
    return today in result["data"]["dateList"]


def prefetch_next_price(province: str | None = None) -> dict | None:
    """提前约 2 小时取新批次；advance=False 说明没有新价"""
    params = {"province": province} if province else None
    resp = requests.get(ADVANCE_URL, params=params,
                        headers={"X-API-Key": API_KEY}, timeout=10)
    result = resp.json()
    if result.get("code") != 0:
        print("查询失败：", result.get("msg"))
        return None
    data = result["data"]
    print(f"批次生效日期 {data['effectiveDate']}，是否新价：{data['advance']}")
    return data


if __name__ == "__main__":
    today = datetime.now().strftime("%Y-%m-%d")
    if is_adjust_day(today):
        prefetch_next_price("重庆市")
    else:
        print("今天不是调价日，沿用本地缓存")
```

### 4.5 Java（Hutool）

```java
String body = HttpRequest.get("https://api.xujian.tech/openapi/oilprice/advance")
        .header("X-API-Key", apiKey)
        .timeout(10000)
        .execute().元年body();

JSONObject json = JSONUtil.parseObj(body);
if (json.getInt("code") != 0) {
    System.out.println("查询失败：" + json.getStr("msg"));
    return;
}
JSONObject data = json.getJSONObject("data");
System.out.println("生效日期：" + data.getStr("effectiveDate")
        + "，是否新价：" + data.getBool("advance"));
```

### 4.6 JavaScript（Node 18+）

```javascript
const res = await fetch("https://api.xujian.tech/openapi/oilprice/advance", {
  headers: { "X-API-Key": apiKey },
});
const json = await res.json();
console.log(json.data.effectiveDate, json.data.advance);
```

## 五、错误码与常见失败原因

| code | msg（示例） | 处理建议 |
|------|------------|----------|
| 0 | success | 调用成功，用 `advance` 判断是否为提前价格 |
| 500 | 缺少请求头 X-API-Key | 补充 X-API-Key |
| 500 | API Key 无效 / API Key 已停用 | 检查 Key 或重新启用 |
| 500 | 客户不存在或已停用 | 联系平台确认账号状态；联系 V `xujian_cq` |
| 500 | **接口未授权或授权已过期** | 本接口为按年套餐，需后台为该客户授权；续费后重试 |
| 500 | 接口不存在或已停用 | 确认 oilprice.advance 当前是否维护中 |

## 六、接入建议

1. **别在零点之后才去拿新价**：真正有价值的调用窗口是**调价日前一天晚间**（22 点之后），此时 `advance=true`，你有大约两小时去完成内部审批、改价预置和系统通知。
2. **用免费的调价日历排班**：先把当年的调价日期列表拉下来，只在那些日期的前一晚跑任务，一年二十多次，比每天轮询优雅得多。
3. **`advance` 必须参与业务判断**：`false` 表示没有更新价格，返回的是当前生效价。如果不管这个字段直接入库，会把旧价当成新价写进去。
4. **注意这是按年套餐，不是按次**：`balance` 不会因调用而变化。成本已包含在年费里，可以适当提高_internalcache的调用密度，但依然建议先做日历判断。
5. **和实时 / 全量接口配合**：这三个接口是同一份数据的不同视角——实时查单点（0.01 元/次）、全量拉字典（5 元/次）、提前查预售倒数{eqnarray新价（本接口）。按场景组合使用最省。

---

油价提前查询 API：配合免费的调价日历，只在调价日蹲新价 发改委成品油调价是有节奏的：一年大约二十四次，每次在调价日零点切换。做油品定价、运费报价、结算对账的系统，最难处理的不是价格本身，而是「零点切换那一刻」——零点前要用旧价，零点后要用新价，而很多系统在零点附近拿到的还是旧数据。 api.xujian.tech V：xujiancq oilprice.advance 的处理方式很直接：按「当

油价提前查询 API：配合免费的调价日历，只在调价日蹲新价

后端

开发工具

油价提前查询API按年付费360元，配合免费调价日历，在调价日前夜22点后调用可提前获取次日零点生效新价，advance字段标记true即新批次价格。支持省市县查询，本地毫秒响应，适合油品定价、运费报价及结算对账系统在零点切换前预置价格，避免旧数据误用。

JavaScript

Python

JSON

Java

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

油价提前查询 API：配合免费的调价日历，只在调价日蹲新价-腾讯云开发者社区-腾讯云

油价提前查询 API：配合免费的调价日历，只在调价日蹲新价

油价提前查询 API：配合免费的调价日历，只在调价日蹲新价

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐