可以查到明天生效的新价格吗？

不可以。本接口只返回当前已生效的价格（生效日期不晚于今天）。如需提前 2 小时拿到即将生效的价格，请使用 oilprice.advance 提前查询接口。

实时发改委油价查询 API（0#柴油 / 92# / 95# / 98# 汽油）· oilprice.realtime 接口文档

Q: oilprice.realtime 接口怎么收费？

oilprice.realtime 的收费类型为 PER_CALL（按次计费），当前单价 0.0100 元/次，调用前校验余额，余额不足返回「余额不足，请先充值。可联系微信xujian_cq」且不扣费；充值可可联系微信xujian_cq。扣费金额、交易前后余额均记录于交易流水中。

Q: 区一级没有单独定价时返回什么？

接口自动向上回落：区县无数据取该市统一价，市也无数据取该省统一价。返回结果中 city / district 为 null 即表示使用了上一级统一价。

Q: province 传名称还是代码？

两者都可以：传 6 位数字按 adcode 精确匹配，传中文按名称匹配。

Q: 调用需要签名或加密吗？

不需要。XAPI 的接口仅校验请求头 X-API-Key，不做签名、时间戳或加密。

接口概述

一句话说明

oilprice.realtime 返回指定地区、指定油品「当前正在生效」的发改委成品油价格。 系统按「生效日期」分批维护价格，接口始终取 生效日期 <= 今天 的最新批次， 系统中未来生效的价格不会被查出。

接口规格
请求地址	`https://api.xujian.tech/openapi/oilprice/realtime`
请求方式	GET
鉴权方式	请求头 `X-API-Key`（不做签名与加密）
接口编码	`oilprice.realtime`
收费类型	PER_CALL（按次计费，0.0100 元/次）
响应格式	JSON，`Content-Type: application/json;charset=UTF-8`
是否需要授权	否（无需授权，API Key 有效且余额充足即可调用）
数据更新频率	国家发改委约每 10 个工作日调价一次，运营在调价当日维护入库
典型用途	油价展示、物流成本核算、加油卡结算、价格监测与比价

快速开始

把 你的APIKey 换成控制台获取的 API Key，查询重庆市当前生效的 0#柴油价格：

cURL

curl -s "https://api.xujian.tech/openapi/oilprice/realtime?province=%E9%87%8D%E5%BA%86%E5%B8%82&oilName=0%23%E6%9F%B4%E6%B2%B9" \
  -H "X-API-Key: 你的APIKey"

查到区县一级（区未单独定价时自动回落到市级 / 省级统一价）

cURL

curl -s "https://api.xujian.tech/openapi/oilprice/realtime?province=%E6%B5%99%E6%B1%9F%E7%9C%81&city=%E6%9D%AD%E5%B7%9E%E5%B8%82&district=%E8%A5%BF%E6%B9%96%E5%8C%BA&oilName=95%23%E6%B1%BD%E6%B2%B9" \
  -H "X-API-Key: 你的APIKey"

请求参数

请求头（Header）
参数名	必填	说明
`X-API-Key`	是	控制台获取的 API Key；缺失返回「缺少请求头 X-API-Key」

查询参数（Query）
参数名	必填	类型	说明
`province`	是	String	省名称（如 `重庆市`）或 6 位 adcode（如 `500000`）
`city`	否	String	市名称或 6 位 adcode；不传表示按省级价格匹配
`district`	否	String	区县名称或 6 位 adcode；不传表示按市级价格匹配
`oilName`	是	String	油品中文名，限填： `0#柴油`、`-10#柴油`、`-35#柴油`、 `92#汽油`、`95#汽油`、`98#汽油`

响应参数

顶层字段
字段	类型	说明
`code`	int	0 成功，非 0 失败
`msg`	String	成功为 `success`，失败为具体原因
`data`	Object	业务数据，失败时为 `null`

data 明细（仅对外字段）
字段	类型	说明
`oilName`	String	商品名（油品中文名），与入参一致
`effectiveDate`	String	发改委价格生效日期，格式 `yyyy-MM-dd`（当天 0 点生效）
`price`	BigDecimal	价格（元）
`province` / `provinceCode`	String	命中记录的省名称与 6 位 adcode
`city` / `cityCode`	String	地市名称与代码；`null` 表示该省全省统一价
`district` / `districtCode`	String	区县名称与代码；`null` 表示该市全市统一价
`dataUpdateTime`	String	数据更新时间，格式 `yyyy-MM-dd HH:mm:ss`
`apiCode` / `apiName`	String	接口编码与接口名称
`chargeType`	String	本次计费方式（PER_CALL）
`balance`	BigDecimal	本次扣费后的账户余额
`costMs`	long	接口耗时（毫秒）

响应示例

成功（code = 0）

JSON

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

失败（油品名非法）

JSON

{
  "code": 500,
  "msg": "oilName 取值只能是：0#柴油 / -10#柴油 / -35#柴油 / 92#汽油 / 95#汽油 / 98#汽油",
  "data": null
}

错误码与常见失败原因

code	msg（示例）	处理建议
0	success	调用成功
500	缺少请求头 X-API-Key	在请求头中补充 X-API-Key
500	API Key 无效 / API Key 已停用	检查 Key 是否正确，或在控制台重新启用
500	客户不存在或已停用	联系平台运营确认账号状态（可联系微信xujian_cq）
500	接口不存在或已停用	确认接口编码 oilprice.realtime 当前是否维护中
500	余额不足，请先充值。可联系微信xujian_cq	按次计费接口在调用前校验余额，余额不足时不扣费，充值后重试（可联系微信xujian_cq）
500	province 不能为空 / oilName 不能为空	补齐必填参数
500	未查询到该地区的发改委价格	该地区尚未维护价格，可先调调价周期查询确认当前批次

多语言调用示例

Java（Hutool）

String url = "https://api.xujian.tech/openapi/oilprice/realtime"
        + "?province=" + URLEncoder.encode("重庆市", StandardCharsets.UTF_8)
        + "&oilName=" + URLEncoder.encode("0#柴油", StandardCharsets.UTF_8);
String body = HttpRequest.get(url)
        .header("X-API-Key", apiKey)
        .timeout(5000)
        .execute().body();

Python

import requests

resp = requests.get(
    "https://api.xujian.tech/openapi/oilprice/realtime",
    params={"province": "重庆市", "oilName": "0#柴油"},
    headers={"X-API-Key": api_key},
    timeout=5,
)
print(resp.json())

JavaScript

const url = new URL("https://api.xujian.tech/openapi/oilprice/realtime");
url.searchParams.set("province", "重庆市");
url.searchParams.set("oilName", "0#柴油");

const res = await fetch(url, {headers: {"X-API-Key": apiKey}});
const json = await res.json();

常见问题

这个接口怎么收费？

oilprice.realtime 的收费类型为 PER_CALL（按次计费），当前单价 0.0100 元/次，调用前校验余额，余额不足返回「余额不足，请先充值。可联系微信xujian_cq」且不扣费；充值可可联系微信xujian_cq。扣费金额、交易前后余额均记录于交易流水中。

为什么查不到明天要生效的新价格？

本接口只返回当前已生效的价格（生效日期不晚于今天）。如需提前 2 小时拿到即将生效的价格，请使用提前查询发改委价格（oilprice.advance）。

只传省、不传市和区会返回什么？

按「省统一价」匹配：若该省登记的是全省统一价，直接返回；若该省按市 / 区分别定价，则返回该省第一条匹配记录。建议尽量传全省 / 市 / 区以获得唯一结果。

区一级没有单独定价怎么办？

接口会自动向上回落：区县无数据 → 取该市统一价；市也无数据 → 取该省统一价。返回结果中 city / district 为 null 即表示使用了上一级统一价。

province 传名称还是代码？

两者都可以。传 6 位数字按 adcode 精确匹配，传中文按名称匹配。

调用需要签名或加密吗？