油价调整提前查询 API新价生效前 2 小时拿到调价结果发改委成品油调价是「某日 0 点起生效」但加油站调价预置、物流报价测算、调价日切换对账都需要在此之前就把新价格准备好。提前查询解决的就是这个时间差问题。本文介绍的oilprice.advance接口在新价格生效前 2 小时即可查到即将生效的那批价格返回结果用advance字段明确区分「尚未生效的新价」与「当前生效的价」。api.xujian.techxujian_cq接口速览关键事实说明接口地址https://api.xujian.tech/openapi/oilprice/advance接口编码oilprice.advance请求方式GET参数放 Query String鉴权方式请求头X-API-Key不做签名、时间戳或加密业务入参无province/city/district均可选不传返回全部地区返回核心字段effectiveDate/advance/total/list[]与全量接口结构一致收费方式按年付费360 元/年需后台为该客户授权提前量固定 2 小时不可配置包年内调用不额外扣费不消耗账户余额balance前后一致一、能力边界能做什么、不能做什么能做的把「查询基准日」提前 2 小时。服务端取「当前时间 2 小时」所在的日期作为目标日期再取不晚于该日期的最新生效批次。9/24 22:00 调用 → 目标日期是 9/25 → 能查到 9/25 0 点生效的那批价格advance true9/24 21:00 调用 → 目标日期仍是 9/24 → 只能查到 9/24 及之前生效的价格advance false。不能做的凭空算出还没公布的价格。能否提前查到取决于平台是否已经在系统里维护好下一批价格。如果新批次价格还没录入即使在生效前 1 分钟调用返回的仍是当前生效的批次advance false。换句话说这个接口提供的是「提前 2 小时的查询窗口」不是「保证提前 2 小时拿到新价」的承诺。调用方必须处理advance false的情况那是「暂时还没有新价」不是接口出错。二、哪些业务需要这一步场景具体用法加油站调价预置前一晚轮询拿到新价写入待生效表0 点自动切换物流报价提前测算调价日前一天用新价报价避免 0 点后价格跳变造成亏损调价日切换对账0 点前后各查一次确认系统切价成功车队月度预算测算按即将生效的价格重算下月燃油预算油价变动预警推送检测advance变为true时向运营 / 客户推送调价提醒加油卡结算预案提前生成新的结算单价避免跨零点交易对不上账加油站挂牌牌价更新提前生成新牌价减少 0 点人工改价压力财务测算与毛利预估按新价测算调价后毛利变化辅助定价决策价格监测大屏大屏提前展示「即将生效」状态便于运营排班三、请求参数请求头参数名必填说明X-API-Key是开发者 API Key缺失或无效直接返回失败查询参数全部可选参数名必填类型示例说明province否String重庆市/500000省名称或 6 位 adcode不传返回全部地区city否String杭州市/330100市名称或 6 位 adcodedistrict否String西湖区/330106区县名称或 6 位 adcode地区匹配逻辑与实时接口一致区县 → 市 → 省逐级回落查不到则按省返回。名称需与标准行政区划名称完全一致如重庆市推荐直接传 6 位 adcode避免名称对不上导致返回空列表。四、返回字段4.1 顶层字段字段类型说明codeint0成功非 0 失败统一为500msgString成功为success失败为具体原因dataObject业务数据失败时为null4.2 data 字段字段类型示例说明effectiveDateString2026-09-25返回价格批次的生效开始时间yyyy-MM-dd无数据时为nulladvancebooleantruetrue 尚未生效的新价格false 当前生效的价格totalint1本次返回条数listArray[…]价格明细字段与全量接口oilprice.all的list[]完全一致apiCode/apiNameStringoilprice.advance / 提前查询发改委价格接口编码与接口名称chargeTypeStringYEARLY本次计费方式balanceBigDecimal100.0000账户余额包年套餐内不扣费交易前后一致costMslong8服务端处理耗时毫秒不含公网传输时间4.3 list[] 明细字段字段类型说明effectiveDateString该行价格生效日期province/provinceCodeString省名称与 6 位 adcodecity/cityCodeString地市名称与代码null 全省统一价district/districtCodeString区县名称与代码null 全市统一价priceDiesel0/priceDiesel10/priceDiesel35BigDecimal0# / -10# / -35# 柴油价格元未维护时为nullpriceGas92/priceGas95/priceGas98BigDecimal92# / 95# / 98# 汽油价格元dataUpdateTimeString数据更新时间yyyy-MM-dd HH:mm:ss4.4 判断拿到的到底是不是新价两种方式推荐两个都用看advance字段——最直接自己比较effectiveDate与当天日期——effectiveDate大于今天就说明是尚未生效的批次。functionisNewPrice(data){consttodaynewDate().toISOString().slice(0,10);returndata.advancetrue||data.effectiveDatetoday;}五、调用示例5.1 curl# 不带参数返回全部地区curl-shttps://api.xujian.tech/openapi/oilprice/advance\-HX-API-Key: 你的APIKey# 只看某个省推荐用 adcodecurl-shttps://api.xujian.tech/openapi/oilprice/advance?province500000\-HX-API-Key: 你的APIKey5.2 JavaHutoolimportcn.hutool.http.HttpRequest;importcn.hutool.json.JSONObject;importcn.hutool.json.JSONUtil;importjava.net.URLEncoder;importjava.nio.charset.StandardCharsets;importjava.time.LocalDate;publicclassOilPriceAdvanceClient{privatestaticfinalStringAPI_URLhttps://api.xujian.tech/openapi/oilprice/advance;/** * 查询即将生效或当前生效的发改委价格 * * param apiKey 开发者 API Key需已开通按年授权 * param province 省名称或 adcode可空 * return data 节点失败返回 null */publicstaticJSONObjectfetch(StringapiKey,Stringprovince){StringurlAPI_URL;if(province!null!province.isEmpty()){url?provinceURLEncoder.encode(province,StandardCharsets.UTF_8);}JSONObjectjsonJSONUtil.parseObj(HttpRequest.get(url).header(X-API-Key,apiKey).timeout(30000).execute().body());if(json.getInt(code)null||json.getInt(code)!0){System.out.println(查询失败json.getStr(msg));returnnull;}returnjson.getJSONObject(data);}publicstaticvoidmain(String[]args){JSONObjectdatafetch(你的APIKey,500000);if(datanull){return;}StringeffectiveDatedata.getStr(effectiveDate);booleanadvancedata.getBool(advance,false);if(advance){System.out.println(拿到即将生效的新价生效日期effectiveDate);}else{System.out.println(暂无更新的价格当前生效批次effectiveDate);}// 与当天日期交叉校验一次避免只依赖 advanceif(effectiveDate!nulleffectiveDate.compareTo(LocalDate.now().toString())0){System.out.println(确认该批次尚未生效);}}}5.3 Pythonimportrequestsfromdatetimeimportdatedeffetch_advance(api_key:str,province:strNone)-dict: 查询即将生效或当前生效的发改委价格 Returns: dict: 成功返回 data失败返回 None params{province:province}ifprovinceelse{}resultrequests.get(https://api.xujian.tech/openapi/oilprice/advance,paramsparams,headers{X-API-Key:api_key},timeout30,).json()ifresult.get(code)!0:print(查询失败,result.get(msg))returnNonereturnresult[data]defdescribe(data:dict)-str:把结果翻译成人话区分「新价」与「当前价」ifnotdataordata.get(total,0)0:return暂无价格数据ifdata[advance]ordata[effectiveDate]date.today().isoformat():returnf即将生效的新价{data[effectiveDate]}起生效returnf暂无更新的价格当前生效批次为{data[effectiveDate]}if__name____main__:datafetch_advance(你的APIKey,500000)print(describe(data))5.4 JavaScriptNode 18asyncfunctionfetchAdvance(apiKey,province){consturlnewURL(https://api.xujian.tech/openapi/oilprice/advance);if(province)url.searchParams.set(province,province);const{code,msg,data}awaitfetch(url,{headers:{X-API-Key:apiKey},}).then((r)r.json());if(code!0){console.warn(查询失败,msg);returnnull;}consttodaynewDate().toISOString().slice(0,10);constisNewdata.advancetrue||data.effectiveDatetoday;console.log(isNew?新价${data.effectiveDate}生效:当前批次${data.effectiveDate});returndata;}六、返回示例6.1 成功 —— 查到即将生效的新价格advance true{code:0,msg:success,data:{effectiveDate:2026-09-25,advance:true,total:1,list:[{effectiveDate:2026-09-25,provinceCode:500000,province:重庆市,cityCode:null,city:null,districtCode:null,district:null,priceDiesel0:7.41,priceDiesel10:7.86,priceDiesel35:8.20,priceGas92:8.02,priceGas95:8.48,priceGas98:9.55,dataUpdateTime:2026-09-24 22:05:00}],apiCode:oilprice.advance,apiName:提前查询发改委价格,chargeType:YEARLY,balance:100.0000,costMs:8}}6.2 成功 —— 无更新价格返回当前生效价格advance false{code:0,msg:success,data:{effectiveDate:2026-09-11,advance:false,total:1,list:[{effectiveDate:2026-09-11,provinceCode:500000,province:重庆市,cityCode:null,city:null,districtCode:null,district:null,priceDiesel0:7.28,priceDiesel10:7.72,priceDiesel35:8.05,priceGas92:7.86,priceGas95:8.31,priceGas98:9.36,dataUpdateTime:2026-09-11 09:00:00}],apiCode:oilprice.advance,apiName:提前查询发改委价格,chargeType:YEARLY,balance:100.0000,costMs:7}}6.3 失败 —— 未授权或授权已过期不扣费{code:500,msg:接口未授权或授权已过期,data:null}七、落地实践7.1 加油站调价预置在调价日前一晚轮询拿到新价后写入本地待生效表0 点自动切换importtimedefpreset_next_price(api_key,province,store:dict,max_wait_hours:int3): 调价日前一晚起轮询直到拿到 advanceTrue 的新价并预置到本地。 拿不到就退出由下一轮定时任务继续绝不把旧价当新价写入。 deadlinetime.time()max_wait_hours*3600whiletime.time()deadline:datafetch_advance(api_key,province)ifdataanddata.get(advance):store[pending]{effectiveDate:data[effectiveDate],list:data[list],}returnTruetime.sleep(600)# 10 分钟一次returnFalse关键设计只有当advance true时才写入待生效表。advance false说明新批次还没录入此时继续沿用当前价绝不能把旧批次当成新价预置。7.2 物流报价提前测算客户在调价日前一天询价用提前查到的新价给报价避免 0 点后价格跳变导致亏损functionquote(data,km,literPer100km){constpdata.list[0]?.priceDiesel0;if(pnull)thrownewError(该地区未维护 0#柴油价格);constcost(km/100)*literPer100km*p;return{cost:Number(cost.toFixed(2)),basis:data.advance?按${data.effectiveDate}生效的新价测算:按当前价测算新价尚未公布,};}报价单里把basis一起给客户能避免后续争议。7.3 调价日切换对账0 点前后各查一次比对effectiveDate是否发生切换确认系统切价成功defcheck_switch(before:dict,after:dict)-str:ifbefore[effectiveDate]after[effectiveDate]:returnf未切换仍为{after[effectiveDate]}新批次可能尚未录入returnf已切换{before[effectiveDate]}→{after[effectiveDate]}7.4 配合免费的调价周期接口排程免费的oilprice.cycle返回当年已登记的调价生效日期列表用它决定哪天晚上需要轮询避免全年无意义地跑任务。八、实践建议永远不要假设advance true。新批次没录入时就是false业务必须有「继续用当前价」的分支。用effectiveDate做幂等。同一生效日期不要重复预置避免覆盖人工调过的价。地区参数用 adcode。中文名需与标准行政区划名称完全一致否则可能返回空列表。轮询间隔别太短。建议 5 ~ 10 分钟一次并设整体超时。油品价格可能是null。与全量接口一致未维护的油品返回null预置时要处理别当 0。授权到期前提前续费。授权过期会直接返回失败调价日正好撞上过期会很被动。区分「未授权」与「暂无新价」。前者是code500接口未授权或授权已过期后者是code0advancefalse两者的告警级别应不同。不要把它当实时行情。返回的是发改委公布的批次最高零售价不是加油站挂牌价或成交价。九、错误码与排查codemsg示例处理建议0success调用成功用advance判断是否拿到新价500缺少请求头 X-API-Key在请求头补充X-API-Key不扣费500API Key 无效 / API Key 已停用检查 Key 是否正确或在控制台重新启用不扣费500客户不存在或已停用联系平台确认账号状态不扣费500接口不存在或已停用确认oilprice.advance当前是否维护中不扣费500接口未授权或授权已过期本接口为按年套餐需后台为该客户授权办理或续费后重试不扣费本接口为包年模式不会出现「余额不足」类错误包年内调用不消耗账户余额。十、计费与接入项目说明收费方式按年付费YEARLY360 元/年是否需要授权是需后台为该客户开通授权并设定有效期包年内调用不额外扣费不消耗账户余额balance前后一致不计费场景Key 缺失 / 无效、客户停用、接口停用、未授权或授权过期提前量固定 2 小时不可配置接入流程注册开发者账号 → 联系平台开通本接口的按年授权 → 控制台创建 API Key → 请求头带上X-API-Key即可调用无需签名或加密。控制台可查看调用量、扣费流水与余额。服务站点api.xujian.tech纯文本域名不做跳转。接口试用、授权与充值咨询可在控制台提交工单或联系 Vxujian_cq。同系列接口oilprice.realtime实时发改委价格查询0.01 元/次查当前生效的单地区单油品价格oilprice.all全量发改委价格查询一次拉回当前生效批次的全部地区价格oilprice.cycle发改委调价周期查询免费返回当年调价生效日期列表用于排程。十一、小结提前查询接口解决的不是「算出未来价格」而是「在价格正式生效前把已经确定的下一批价格提前送到你手里」。它把「当前生效」和「即将生效」用advanceeffectiveDate表达清楚让调价预置、报价测算、切换对账这些事可以在 0 点之前完成。四个关键取舍不保证提前 2 小时拿到新价能否提前取决于平台是否已录入下一批价格未录入时返回advance false按年付费 后台授权包年内调用不额外扣费授权过期直接失败不扣费参数全可选不传地区返回全部传了按「区县 → 市 → 省」回落建议用 6 位 adcode字段与全量接口一致list[]结构完全相同油品未维护时为null解析时务必判空。