发改委调价周期查询接口（oilprice.cycle）：免费安排拉价时点

这个接口能解决什么问题

国家发改委约每 10 个工作日调整一次成品油价格。oilprice.cycle 返回当年（或指定年份）的调价生效日期列表，每个日期表示「当天 0 点起新价格生效」。有了这份日历，你就可以在调价日当天再去拉全量 / 实时价格，而平时不必频繁调用，从而把成本压到最低。

一句话说明

oilprice.cycle 是免费的「调价日历」，用来安排拉取油价的时间点、做调价提醒与缓存失效策略。

适用场景

安排拉取油价的时间点：只在调价日触发全量拉取
调价提醒：在调价前给用户发通知
成本核算日历：按调价周期做成本预算
缓存失效策略：以调价日为缓存刷新锚点

接口规格

接口规格
请求地址	`https://api.xujian.tech/openapi/oilprice/cycle`
请求方式	GET
鉴权方式	请求头 `X-API-Key`
接口编码	`oilprice.cycle`
收费类型	免费（FREE，0 元，不扣费）
响应格式	JSON，`application/json（charset=UTF-8）`
典型用途	安排拉价时点、调价提醒、成本核算日历、缓存策略

如何调用

cURL

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

查询指定年份

cURL

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

返回示例（code = 0）

JSON

{
  "code": 0,
  "msg": "success",
  "data": {
    "year": "2026",
    "dates": ["2026-01-02", "2026-01-16", "2026-02-06", "2026-02-19"],
    "apiCode": "oilprice.cycle",
    "apiName": "发改委调价周期查询",
    "chargeType": "FREE",
    "balance": 100.0000,
    "costMs": 15
  }
}

计费说明

完全免费。有可用的 X-API-Key 即可调用，不扣费、不消耗余额，是油价类应用最划算的「基础设施」之一。

常见问题

数据来源？ 运营依据国家发改委公告在管理端维护，可在「油品发改价格 → 调价周期」中查看。
能查历史年份吗？ 可以，传 year 参数即可；默认返回当年。
和 advance 接口怎么配合？ cycle 告诉你调价日，advance 让你在调价前 2 小时拿到新价，实时 / 全量接口用于正式取数。