发改委调价周期查询 API（免费 · 每 10 个工作日一次）· oilprice.cycle 接口文档

Q: cycleDate 是公布日还是生效日？

是生效日：当天 0 点起新价格生效，与价格数据中的 effectiveDate 口径一致。

Q: 免费接口会写调用流水吗？

会。免费接口不扣费、不扣余额，仍会写一条 amount=0 的流水并累加调用次数，便于在控制台查看用量。

接口概述

一句话说明

oilprice.cycle 返回当年（或指定年份）发改委成品油的调价生效日期列表。 每个日期表示「当天 0 点起新价格生效」。配合全量价格查询即可做到「只在调价日拉一次」，显著降低调用成本。

接口规格
请求地址	`https://api.xujian.tech/openapi/oilprice/cycle`
请求方式	GET
鉴权方式	请求头 `X-API-Key`（不做签名与加密）
接口编码	`oilprice.cycle`
收费类型	FREE（免费，0 元，不扣费、不消耗余额）
响应格式	JSON，`Content-Type: application/json;charset=UTF-8`
是否需要授权	否（免费接口，API Key 有效即可调用，无需购买套餐或单独授权）
数据来源	运营依据国家发改委公告在管理端维护，可在「油品发改价格 → 调价周期」中查看
典型用途	安排拉取油价的时间点、调价提醒、成本核算日历、缓存失效策略

快速开始

cURL

curl -s "https://api.xujian.tech/openapi/oilprice/cycle" \
  -H "X-API-Key: 你的APIKey"

查询指定年份

cURL

curl -s "https://api.xujian.tech/openapi/oilprice/cycle?year=2026" \
  -H "X-API-Key: 你的APIKey"

请求参数

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

查询参数（Query）
参数名	必填	类型	说明
`year`	否	Integer	年份，如 `2026`；不传默认当年。取值 2000 ~ 2999

响应参数

data 字段
字段	类型	说明
`year`	int	查询年份
`total`	int	调价次数（约 24 次/年）
`list`	Array	调价周期列表，按日期升序
`list[].cycleDate`	String	调价生效日期 `yyyy-MM-dd`（当天 0 点新价格生效）
`list[].remark`	String	备注，无则为 `null`
`apiCode` / `apiName`	String	接口编码与接口名称
`chargeType`	String	本次计费方式（FREE）
`balance`	BigDecimal	账户余额（免费接口不扣费）
`costMs`	long	接口耗时（毫秒）

响应示例

成功（code = 0）

JSON

{
  "code": 0,
  "msg": "success",
  "data": {
    "year": 2026,
    "total": 2,
    "list": [
      {"cycleDate": "2026-09-11", "remark": "2026 年 9 月第 1 次调价"},
      {"cycleDate": "2026-09-24", "remark": "2026 年 9 月第 2 次调价"}
    ],
    "apiCode": "oilprice.cycle",
    "apiName": "发改委调价周期查询",
    "chargeType": "FREE",
    "balance": 100.0000,
    "costMs": 4
  }
}

失败（未传 API Key）

JSON

{
  "code": 500,
  "msg": "缺少请求头 X-API-Key",
  "data": null
}

错误码与常见失败原因

code	msg（示例）	处理建议
0	success	调用成功；`total` 为 0 表示该年份尚未维护调价周期
500	缺少请求头 X-API-Key	在请求头中补充 X-API-Key
500	API Key 无效 / API Key 已停用	检查 Key 是否正确，或在控制台重新启用
500	客户不存在或已停用	联系平台运营确认账号状态（可联系微信xujian_cq）
500	接口不存在或已停用	确认接口编码 oilprice.cycle 当前是否维护中
500	year 取值应在 2000 ~ 2999 之间	修正年份参数

多语言调用示例

Java（Hutool）

String body = HttpRequest.get("https://api.xujian.tech/openapi/oilprice/cycle")
        .header("X-API-Key", apiKey)
        .timeout(5000)
        .execute().body();

Python

import requests

resp = requests.get(
    "https://api.xujian.tech/openapi/oilprice/cycle",
    params={"year": 2026},
    headers={"X-API-Key": api_key},
    timeout=5,
)
print(resp.json()["data"]["list"])

JavaScript

const res = await fetch("https://api.xujian.tech/openapi/oilprice/cycle", {
  headers: {"X-API-Key": apiKey}
});
const json = await res.json();

常见问题

这个接口收费吗？

oilprice.cycle 接口完全免费，收费类型为 FREE，调用不扣费、不消耗账户余额，也不需要单独授权，仅需在请求头携带有效的 X-API-Key。

调价周期是怎么来的？

国家发改委约每 10 个工作日调整一次成品油价格（遇节假日顺延），运营人员依据官方公告在管理端登记生效日期，接口原样返回。

为什么某一年返回空列表？

该年份尚未维护调价周期。可去掉 year 参数查询当年，或联系平台补充。

cycleDate 是调价公布日还是生效日？

是生效日：当天 0 点起新价格生效，与价格数据中的 effectiveDate 口径一致。

免费接口也写调用流水吗？

会。免费接口不扣费、不扣余额，仍会写一条 amount = 0 的流水并累加调用次数，便于在控制台查看用量。

发改委调价周期查询 API（oilprice.cycle）