# 实时发改委油价查询 API：按省市区查今天生效的六种油品价格

加油站结算、物流成本核算、车队油补、油价看板，都需要一个共同的基准：**当前生效的发改委成品油价格**。它和加油站挂牌价不是一回事，却是最高指导价、批发结算和企业内部核算最常用的口径。`oilprice.realtime` 把它做成一个 GET 接口：**按省（必填）+ 市 + 区县 + 油品名查询，返回当前生效的价格与生效日期**。

计费口径：**查不到价格时不收费**。参数缺失、油品名非法、该地区暂未维护价格，均返回失败且不扣费。详见第九节。

- ``api.xujian.tech``
- ``xujian_cq``

## 接口速览

| 关键事实 | 说明 |
|------|------|
| 接口地址 | `https://api.xujian.tech/openapi/oilprice/realtime` |
| 接口编码 | `oilprice.realtime` |
| 请求方式 | GET |
| 鉴权方式 | 请求头 `X-API-Key`，不做签名、时间戳或加密 |
| 必填参数 | `province`、`oilName` |
| 支持油品 | 0#柴油 / -10#柴油 / -35#柴油 / 92#汽油 / 95#汽油 / 98#汽油 |
| 返回内容 | 单个油品的价格、生效日期、省市区名称与代码、数据更新时间 |
| 计价 | 按次计费，**0.01 元/次** |
| 不计费场景 | 参数为空 / 油品名非法、服务未启用或未配置、鉴权失败、余额不足、未查到价格 |
| 建议超时 | 10 秒以上（`costMs` 为真实耗时） |

## 一、使用中最容易搞混的三件事

### 1. 返回的是“当前生效”，不含明天的新价

接口只取**生效日期不晚于今天**的最新批次。今天是 10 月 24 日，明天零点要调价，那么今天查到的还是旧价。要提前拿到即将生效的新价，请用 `oilprice.advance`（按年付费并可授权提前 2 小时查询）。

### 2. 区县没有单独定价时会自动向上回落

中国的成品油定价按省 / 市分级，大部分区县没有独立价格。接口的规则是：

| 情况 | 返回 |
|------|------|
| 该区县有单独定价 | `district` / `districtCode` 有值 |
| 区县无数据，该市有统一价 | `city` / `cityCode` 有值，`district` 为 `null` |
| 市也无数据，全省统一价 | `city` 与 `district` 均为 `null`，但有 `province` / `provinceCode` |

> 判断用了哪一级的价格，看 `city` / `district` 是否为 `null` 即可——字段为空就说明使用了上一级的统一价。

### 3. 六个油品名必须原样传入

`oilName` 是白名单匹配，取值只能是 `0#柴油`、`-10#柴油`、`-35#柴油`、`92#汽油`、`95#汽油`、`98#汽油`，写「柴油」「0号柴油」都会报错。南方地区常没有 -35#柴油的价格，该油品可能查不到（不计费）。

## 二、请求参数

| 参数名 | 位置 | 必填 | 类型 | 示例 | 说明 |
|--------|------|------|------|------|------|
| `X-API-Key` | Header | 是 | String | — | 开发者 API Key |
| `province` | Query | 是 | String | 重庆市 / 500000 | 省级名称或 6 位 adcode |
| `city` | Query | 否 | String | 铜梁区所在的市 / 500100 | 市级名称或 6 位 adcode |
| `district` | Query | 否 | String | 510117 | 区县级名称或 6 位 adcode |
| `oilName` | Query | 是 | String | 92#汽油 | 油品中文名，取值见上表 |

> 省市县三种写法都支持：**中文名称或 6 位行政区划代码**。传 6 位数字时按 adcode 精确匹配，传中文按名称匹配。adcode 可以从免费的 `region.query` 接口获取。

## 三、返回字段

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `code` | int | 0 | `0` 成功，非 0 失败（统一 `500`） |
| `msg` | String | success | 成功 `success`，失败为具体原因 |
| `data.oilName` | String | 92#汽油 | 商品名（油品中文名） |
| `data.effectiveDate` | String | 2026-10-10 | 价格生效日期（`YYYY-MM-DD`） |
| `data.price` | BigDecimal | 7.82 | 价格（元） |
| `data.provinceCode` | String | 500000 | 省级代码 |
| `data.province` | String | 重庆市 | 省级名称 |
| `data.cityCode` | String | 500000 | 地市代码，`null` 表示全省统一价 |
| `data.city` | String | 重庆市 | 地市名称，`null` 表示全省统一价 |
| `data.districtCode` | String | null | 区县代码，`null` 表示全市统一价 |
| `data.district` | String | null | 区县名称，`null` 表示全市统一价 |
| `data.dataUpdateTime` | String | 2026-10-10 09:15:00 | 数据更新时间（`YYYY-MM-DD HH:mm:ss`） |
| `data.apiCode` | String | oilprice.realtime | 接口编码 |
| `data.chargeType` | String | PER_CALL | 计费类型 |
| `data.balance` | BigDecimal | 99.9900 | 扣费后余额（元） |
| `data.costMs` | Long | 120 | 本次调用耗时（毫秒） |

## 四、调用示例

### 4.1 curl

```bash
curl -s -G "https://api.xujian.tech/openapi/oilprice/realtime" \
  --data-urlencode "province=重庆市" \
  --data-urlencode "oilName=92#汽油" \
  -H "X-API-Key: 你的APIKey"

# 省市区三级 + 指定油品
curl -s -G "https://api.xujian.tech/openapi/oilprice/realtime" \
  --data-urlencode "province=浙江省" \
  --data-urlencode "city=杭州市" \
  --data-urlencode "district=西湖区" \
  --data-urlencode "oilName=95#汽油" \
  -H "X-API-Key: 你的APIKey"
```

### 4.2 Java

```java
String url = "https://api.xujian.tech/openapi/oilprice/realtime"
        + "?province=" + URLEncoder.encode("重庆市", StandardCharsets.UTF_8)
        + "&oilName=" + URLEncoder.encode("92#汽油", StandardCharsets.UTF_8);

HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(url))
        .header("X-API-Key", apiKey)
        .timeout(Duration.ofSeconds(10))
        .GET()
        .build();

String json = HttpClient.newHttpClient()
        .send(request, HttpResponse.BodyHandlers.ofString(StandardCharsets.UTF_8))
        .body();
```

### 4.3 Python

```python
import requests

OIL_NAMES = ["0#柴油", "-10#柴油", "-35#柴油", "92#汽油", "95#汽油", "98#汽油"]


def realtime_price(api_key: str, province: str, oil_name: str,
                   city: str = None, district: str = None) -> dict | None:
    """查询当前生效油价；查不到返回 None（不扣费）"""
    params = {"province": province, "oilName": oil_name}
    if city:
        params["city"] = city
    if district:
        params["district"] = district

    resp = requests.get(
        "https://api.xujian.tech/openapi/oilprice/realtime",
        params=params,
        headers={"X-API-Key": api_key},
        timeout=10,
    )
    result = resp.json()
    if result.get("code") != 0:
        print("查询失败（不收费）：", result.get("msg"))
        return None
    return result["data"]
```

### 4.4 JavaScript

```javascript
const url = new URL("https://api.xujian.tech/openapi/oilprice/realtime");
url.searchParams.set("province", "500000");   // 也支持中文名
url.searchParams.set("oilName", "92#汽油");

const { code, msg, data } = await fetch(url, { headers: { "X-API-Key": API_KEY } })
  .then((r) => r.json());

if (code === 0) {
  console.log(`${data.oilName} ${data.price} 元，生效于 ${data.effectiveDate}`);
} else {
  console.warn("查询失败（不收费）：", msg);
}
```

## 五、返回示例

直辖市，全省统一价：

```json
{
  "code": 0,
  "msg": "success",
  "data": {
    "oilName": "92#汽油",
    "effectiveDate": "2026-10-10",
    "price": 7.82,
    "provinceCode": "500000",
    "province": "重庆市",
    "cityCode": "500000",
    "city": "重庆市",
    "districtCode": null,
    "district": null,
    "dataUpdateTime": "2026-10-10 09:15:00",
    "apiCode": "oilprice.realtime",
    "apiName": "实时发改委价格查询",
    "chargeType": "PER_CALL",
    "balance": 99.9900,
    "costMs": 120
  }
}
```

查不到时的返回（不计费）：

```json
{
  "code": 500,
  "msg": "未查询到该地区「-35#柴油」的发改委价格",
  "data": null
}
```

## 六、落地实践

### 6.1 六种油品一次拉全

接口一次只返回一个油品，想要完整油价表就循环六次——六次调用合计 6 分钱，完全可以接受：

```python
def price_table(api_key: str, province: str, city: str = None) -> dict:
    """拉齐六种油品的价格表；某些油品当地不供应时记为 None"""
    table = {}
    for oil in OIL_NAMES:
        d = realtime_price(api_key, province, oil, city=city)
        table[oil] = d["price"] if d else None
    return table
```

> 如果需要全国省市区六种油品的全量数据（大约数千条），请改用 `oilprice.all`（5 元/次）一次取回，比逐个地区循环便宜得多。

### 6.2 用 `city` / `district` 判空识别价格层级

```java
public String priceLevel(JSONObject data) {
    if (data.getString("districtCode") != null) {
        return "区县级定价";
    }
    if (data.getString("cityCode") != null) {
        return "地市级统一价";
    }
    return "省级统一价";
}
```

### 6.3 与免费接口配合刷新

油价约每 10 个工作日调一次。聪明的做法是**只在调价日刷新**：先用免费的 `oilprice.cycle` 拿到当年调价日期列表，当天拉一次全量，其余时间读本地缓存。

```python
def need_refresh(cycle_dates: list[str], today: str) -> bool:
    return today in cycle_dates
```

## 七、实践建议

1. **油品名按白名单原样传**：「0#柴油」不是「0号柴油」，写错直接报错且不计费。
2. **省市优先传 adcode**：中文名称存在同名的可能（多个「高新区」），6 位代码最稳；adcode 可从 `region.query` 免费获取。
3. **看 `city` / `district` 是否为 `null` 判断价格层级**，别假设传了区县就一定返回区县级价格。
4. **只查当前生效价**：要提前知道即将生效的新价请用 `oilprice.advance`。
5. **结果按天缓存**：一天之内价格不变，同省同油品无需重复调用。
6. **某些油品查不到是正常的**：南方多数地区没有 -35#柴油，这类失败不扣费，按“无价”处理即可，不要当 0。

## 八、错误码与排查

| code | msg（示例） | 处理建议 |
|------|-------------|----------|
| 0 | success | 调用成功 |
| 500 | 缺少请求头 X-API-Key / API Key 无效 / 已停用 | 检查请求头与 Key 状态 |
| 500 | province 不能为空 | 补充 `province`；不计费 |
| 500 | oilName 取值只能是：0#柴油 / -10#柴油 / -35#柴油 / 92#汽油 / 95#汽油 / 98#汽油 | 按白名单传值；不计费 |
| 500 | 未查询到该地区的发改委价格 | 确认地区是否有数据；不计费 |
| 500 | 未查询到该地区「-35#柴油」的发改委价格 | 该地区未维护该油品（如南方无 -35#柴油），按无价处理；不计费 |

配套接口：`oilprice.cycle`拿当年调价日期列表，`oilprice.all`（5 元/次）一次取回全国全量价格，`oilprice.advance`（360 元/年，需授权）提前 2 小时拿新价。四个接口按“查日历 → 按天缓存 → 调价日批量刷新”的顺序组合，成本可以压到很低。

实时发改委油价查询 API：按省市区查今天生效的六种油品价格 加油站结算、物流成本核算、车队油补、油价看板，都需要一个共同的基准：当前生效的发改委成品油价格。它和加油站挂牌价不是一回事，却是最高指导价、批发结算和企业内部核算最常用的口径。oilprice.realtime 把它做成一个 GET 接口：按省（必填）+ 市 + 区县 + 油品名查询，返回当前生效的价格与生效日期。 计费口径：查不到价格

实时发改委油价查询 API：按省市区查今天生效的六种油品价格

人工智能

实时发改委油价查询API支持按省市区及油品名查询当前生效的成品油价格，覆盖六种常见油品，价格数据与生效日期实时同步。接口按次计费（0.01元/次），查不到价格不收费，支持省级、地市级、区县级三级价格回落机制，适配加油站结算、物流成本核算等场景，并提供多语言调用示例及完整错误码说明。

JavaScript

Python

JSON

Java

让每一个 Agent，都跑在云上

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

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

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

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

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

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

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

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

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

社区新版编辑器体验调研

实时发改委油价查询 API：按省市区查今天生效的六种油品价格-腾讯云开发者社区-腾讯云

实时发改委油价查询 API：按省市区查今天生效的六种油品价格

实时发改委油价查询 API：按省市区查今天生效的六种油品价格

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐