成品油调价日历 API今年每一次调价生效日期一次拿到免费油价不是每天变但什么时候会变是有规律的国家发改委约每 10 个工作日调整一次成品油价格。对加油站、物流、车队这类业务来说知道「下一次调价是哪天」比知道「今天多少钱」更能决定动作——要不要提前报价、要不要提前改牌价、要不要在调价前一天跑一次预查。oilprice.cycle接口只做一件事返回某一年已登记的调价生效日期列表。免费、一个可选参数、十几毫秒返回可以用来给定时任务排程也可以直接做成一张调价日历。接口速览关键事实说明接口地址https://api.xujian.tech/openapi/oilprice/cycle接口编码oilprice.cycle请求方式GET参数放 Query String鉴权方式请求头X-API-Key不做签名、时间戳或加密业务入参仅可选的year取值 2000 ~ 2999缺省为当年返回核心字段year/total/list[]cycleDateremark收费方式免费FREE0 元/次仍需有效 API Key排序按cycleDate升序单次耗时平均约 15 毫秒响应体costMs为本次真实耗时数据来源运营依据国家发改委公告在管理端登记生效日期接口原样返回一、哪些业务需要这一步场景具体用法调价日历展示直接渲染成年度调价日历运营一眼看到下次调价日定时任务排程只在调价日前后触发重价任务避免每天空跑提前查价触发调价日前一天晚上调用提前查询接口拿即将生效的新价加油站排班调价日 0 点需要改牌价提前安排值班与复核物流报价有效期报价单标注「油价基准日 下次调价日」减少争议车队预算测算按年内剩余调价次数估算燃油成本波动区间财务测算结合调价节奏做季度毛利敏感性分析价格监控大屏大屏展示距离下次调价还有几天提醒推送调价日前一天向运营 / 客户推送提醒历史回溯传往年year复盘某一年共调价多少次、分别在哪些日期二、请求参数2.1 请求头参数名必填说明X-API-Key是开发者 API Key缺失或无效直接返回失败2.2 查询参数参数名必填类型默认示例说明year否Integer当年2026调价年份取值范围2000 ~ 2999越界直接返回失败传year时建议传 4 位年份。查不到该年数据时返回code0且total0表示该年份尚未维护调价周期不是接口报错。三、返回字段3.1 顶层与 data字段类型说明codeint0成功非 0 失败统一为500msgString成功为success失败为具体原因dataObject业务数据失败时为nulldata 字段字段类型示例说明yearint2026查询年份totalint2调价次数全年通常约 24 次listArray[…]调价周期列表按日期升序apiCodeStringoilprice.cycle接口编码apiNameString发改委调价周期查询接口名称chargeTypeStringFREE计费类型balanceBigDecimal100.0000调用后的账户余额元免费不扣费costMslong4本次调用耗时毫秒3.2 list[] 元素字段字段类型示例说明cycleDateString2026-09-11调价生效日期格式yyyy-MM-dd当天 0 点新价格生效remarkString2026 年 9 月第 1 次调价备注无备注时为nullcycleDate的口径与价格数据里的effectiveDate完全一致都是「当天 0 点开始生效」。拿它去比对价格批次日期即可不需要做偏移换算。四、调用示例4.1 curl# 查询当年默认curl-shttps://api.xujian.tech/openapi/oilprice/cycle\-HX-API-Key: 你的APIKey# 查询指定年份curl-s-Ghttps://api.xujian.tech/openapi/oilprice/cycle\--data-urlencodeyear2026\-HX-API-Key: 你的APIKey4.2 JavaHutoolimportcn.hutool.http.HttpRequest;importcn.hutool.json.JSONArray;importcn.hutool.json.JSONObject;importcn.hutool.json.JSONUtil;publicclassOilPriceCycleClient{privatestaticfinalStringAPI_URLhttps://api.xujian.tech/openapi/oilprice/cycle;/** * 查询某年的调价生效日期列表 * * param apiKey 开发者 API Key * param year 年份 2000 ~ 2999传 null 查当年 * return 周期列表失败返回 null */publicstaticJSONArraycycle(StringapiKey,Integeryear){HttpRequestreqHttpRequest.get(API_URL).header(X-API-Key,apiKey).timeout(10000);if(year!null){req.form(year,year);}JSONObjectjsonJSONUtil.parseObj(req.execute().body());if(json.getInt(code)null||json.getInt(code)!0){System.out.println(查询失败json.getStr(msg));returnnull;}returnjson.getJSONObject(data).getJSONArray(list);}publicstaticvoidmain(String[]args){JSONArraylistcycle(你的APIKey,2026);if(listnull){return;}for(inti0;ilist.size();i){System.out.println(list.getJSONObject(i).getStr(cycleDate));}}}4.3 Pythonimportrequestsdefoil_cycle(api_key:str,year:intNone): 查询调价周期 year 为空时查当年返回 list[{cycleDate: 2026-09-11, remark: ...}] params{year:year}ifyearelse{}resprequests.get(https://api.xujian.tech/openapi/oilprice/cycle,paramsparams,headers{X-API-Key:api_key},timeout10,)resultresp.json()ifresult.get(code)!0:print(查询失败,result.get(msg))returnNonereturnresult[data][list]if__name____main__:forrowinoil_cycle(你的APIKey,2026)or[]:print(row[cycleDate],row.get(remark))4.4 JavaScriptasyncfunctionoilCycle(apiKey,year){constqsyear??year${year}:;constrespawaitfetch(https://api.xujian.tech/openapi/oilprice/cycle${qs},{headers:{X-API-Key:apiKey}});constresultawaitresp.json();if(result.code!0){thrownewError(result.msg);}returnresult.data.list;}五、返回示例{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}}某年尚未维护数据时不是失败{code:0,msg:success,data:{year:2027,total:0,list:[],apiCode:oilprice.cycle,apiName:发改委调价周期查询,chargeType:FREE,balance:100.0000,costMs:3}}参数越界{code:500,msg:year 取值应在 2000 ~ 2999 之间,data:null}六、可直接复用的两段代码6.1 算出「下次调价是哪天」fromdatetimeimportdateimportrequestsdefnext_cycle(api_key:str,today:dateNone):返回下一次调价日期字符串没有则 Nonetodaytodayordate.today()rowsoil_cycle(api_key,today.year)or[]future[r[cycleDate]forrinrowsifdate.fromisoformat(r[cycleDate])today]returnmin(future)iffutureelseNone6.2 只在调价前后跑重价任务fromdatetimeimportdate,timedeltadefshould_refresh(api_key:str,today:dateNone):调价日当天及前一天返回 True其余日子不用跑todaytodayordate.today()rowsoil_cycle(api_key,today.year)or[]hit{date.fromisoformat(r[cycleDate])forrinrows}returntodayinhitor(todaytimedelta(days1))inhit这样每天只花一次免费调用就能把「拉价格」这类有成本的任务精确排到调价日其余时间全部跳过。七、实践建议把它当排程依据不要当价格来源。本接口只给日期价格要查实时接口oilprice.realtime或全量接口oilprice.all。每天缓存一次即可。调价周期一年内变动很少本地缓存到当天结束不用每次请求都打。total0不代表出错。新年份尚未维护时就是空列表定时任务要能容忍。注意 0 点生效。调价日的cycleDate当天 0 点新价生效跨零点的交易要按日期归属价别按查询时间。与提前查询接口配合。调价日前一天晚上调用oilprice.advance可以在新价生效前 2 小时拿到结果。不要自己推算调价日。10 个工作日是经验规律遇节假日顺延实际日期以本接口返回为准。免费也有流水。仍会写一条amount 0的流水并累加调用次数方便在控制台核对任务是否在跑。八、错误码与排查codemsg处理建议0success调用成功total0表示该年尚未维护不是错误500缺少请求头 X-API-Key在请求头补充X-API-Key500API Key 无效 / API Key 已停用核对 Key或在控制台重新启用500客户不存在或已停用联系平台确认账号状态500接口不存在或已停用确认oilprice.cycle当前是否维护中500year 取值应在 2000 ~ 2999 之间传 4 位合法年份九、计费与接入项目说明单价免费0 元/次收费方式FREE不扣费、不扣余额流水仍写一条amount 0的流水并累加调用次数是否需要授权否有 Key 即可调用返回条数该年份全部调价日期不做分页接入流程注册开发者账号 → 控制台创建 API Key → 请求头带上X-API-Key即可调用无需签名或加密。控制台可查看调用量、扣费流水与余额。服务站点api.xujian.tech纯文本域名不做跳转。接口试用、数据与充值咨询可在控制台提交工单或联系 Vxujian_cq。十、小结oilprice.cycle是一个典型的「小接口解决大问题」的例子数据只有两个字段但把「什么时候该干活」这件事确定下来之后后面所有跟油价有关的定时任务都能精确到天。几个关键点免费可以放心地每天打一次用来驱动排程口径一致cycleDate与价格数据的effectiveDate同为「当天 0 点生效」可直接比对空列表不是错误新年份未维护时返回total0代码要能容忍别自己推算调价节奏约 10 个工作日一次但会顺延实际以接口登记为准。配套接口查当前生效价格用oilprice.realtime0.01 元/次一次拉回全国用oilprice.all5 元/次想在调价前 2 小时拿到新价用oilprice.advance按年付费需授权。