全量发改委油价查询 API 实战一次拉回全国省市区六种油品价格要在本地建一份成品油价格库最笨的办法是逐个省去查30 多个省 × 6 种油品几十上百次请求还得自己处理「这个省是统一价还是按市定价」。本文介绍一个全量拉取接口一次 GET 请求、零业务参数把系统中当前生效的整批价格省 / 市 / 区县 0#柴油、-10#柴油、-35#柴油、92#、95#、98# 汽油一次性返回适合做本地缓存、离线对账与批量核算。api.xujian.techxujian_cq一、为什么需要「全量」而不是「逐个查」场景逐个查的问题全量接口的做法建本地价格库30 省 × 6 油品 上百次请求初始化慢且容易漏一次请求拿全批批量成本核算每单查一次调用量与延迟都放大拉一次进内存本地匹配数据对账难以确认「我本地那份是不是最新版」用返回的effectiveDate做版本比对地区粒度不确定不知道哪些省按市定价、哪些区县单独定价结果里直接体现city/district是否为null代价也很直接这是一次返回全部数据的高单价接口不适合放在用户请求的链路上高频调用。正确的用法是「低频拉取 本地缓存」。二、接口能力概览2.1 接口基础信息项目说明接口地址https://api.xujian.tech/openapi/oilprice/all接口编码oilprice.all请求方式GET鉴权方式请求头X-API-Key不做签名、时间戳或加密返回格式JSONContent-Type: application/json;charsetUTF-8单次费用5 元/次按次计费是否需要业务入参否无任何查询参数返回条数当前生效批次的全部记录条数取决于库内维护粒度数据来源国家发改委公布的成品油最高零售价由平台运营在调价当日维护入库更新频率国家发改委约每 10 个工作日调价一次实际以返回体dataUpdateTime为准在线文档https://api.xujian.tech/api/oilprice-all价格说明5 元/次取自本项目的接口初始化配置后台「接口管理」可随时调价实际单价请以开发者控制台与在线文档页的显示为准。2.2 请求参数请求头参数名必填说明X-API-Key是开发者 API Key缺失或无效直接返回失败查询参数无。接口故意不做分页与筛选全量数据的定位就是「一次拉全、本地处理」加分页反而容易漏数据。如果你只想查单个地区单油品请用oilprice.realtime0.01 元/次不要浪费一次全量调用。2.3 计费上需要提前知道的一点重要这个接口是**「先鉴权扣费、再查数据」**的模式API Key 有效、账号正常、接口启用、余额充足 →鉴权通过即扣一次 5 元由于没有业务参数鉴权之后基本不会失败即使系统当前没有维护任何价格total 0本次也已经扣费。不扣费的场景只有请求头缺失X-API-Key、API Key 无效或已停用、客户不存在或已停用、接口不存在或已停用、余额不足。5 元/次不便宜接入前建议先确认你的账户余额是否够余额不足会直接返回失败不扣费不会半途扣一部分是否真的需要全量 —— 只查一个省的话oilprice.realtime便宜几个数量级拉取频率是否有必要 —— 价格通常约 10 个工作日才变一次每天拉一次已经很充裕。2.4 数据量大概有多少返回条数取决于平台当前的维护粒度不是固定值维护粒度大致条数全省统一价一个省一条30 条按地市维护300 条量级细化到区县更多这是量级估计不是承诺值。请按total字段做动态处理别在代码里写死条数入库时也别假设「一个省只有一条记录」。三、返回字段详解3.1 顶层字段字段类型说明codeint0成功非 0 失败本接口失败为500msgString结果描述成功为success失败为具体原因dataObject业务数据失败时为null3.2 data 字段字段类型示例说明effectiveDateString2026-09-24本批次价格生效日期yyyy-MM-dd系统暂无数据时为nulltotalint312本次返回的价格条数listArray[…]价格明细列表按province_code→city_code→district_code升序apiCode/apiNameStringoilprice.all / 全量发改委价格查询接口编码与接口名称chargeTypeStringPER_CALL本次计费方式balanceBigDecimal94.9900本次扣费后的账户余额元costMslong12服务端处理耗时毫秒不含公网传输时间3.3 list[] 明细字段字段类型示例说明effectiveDateString2026-09-24该行价格的生效日期province/provinceCodeString浙江省 / 330000省名称与 6 位 adcodecity/cityCodeString杭州市 / 330100地市名称与代码null表示全省统一价district/districtCodeStringnull区县名称与代码null表示全市统一价priceDiesel0BigDecimal7.250#柴油价格元priceDiesel10BigDecimal7.69-10#柴油价格元priceDiesel35BigDecimalnull-35#柴油价格元未维护时为nullpriceGas92BigDecimal7.8392#汽油价格元priceGas95BigDecimal8.2895#汽油价格元priceGas98BigDecimal9.3298#汽油价格元dataUpdateTimeString2026-09-24 09:00:00数据更新时间yyyy-MM-dd HH:mm:ss与单油品接口的重要差别全量接口的油品价格可能是null该地区未维护该油品例如南方很多地区不供应 -35#柴油。处理时请按「无价」处理不要当成 0。而oilprice.realtime遇到这种情况会直接报错不会返回null价格。四、调用示例4.1 curlcurl-shttps://api.xujian.tech/openapi/oilprice/all\-HX-API-Key: 你的APIKey建议先这样手工跑一次把返回的total和effectiveDate看一眼确认数据粒度符合预期再写进定时任务。4.2 JavaHutoolimportcn.hutool.http.HttpRequest;importcn.hutool.json.JSONArray;importcn.hutool.json.JSONObject;importcn.hutool.json.JSONUtil;publicclassOilPriceAllClient{privatestaticfinalStringAPI_URLhttps://api.xujian.tech/openapi/oilprice/all;/** * 拉取当前生效批次的全部发改委价格 * * param apiKey 开发者 API Key * return [生效日期, 明细数组]失败返回 null */publicstaticObject[]fetchAll(StringapiKey){JSONObjectjsonJSONUtil.parseObj(HttpRequest.get(API_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;}JSONObjectdatajson.getJSONObject(data);JSONArraylistdata.getJSONArray(list);System.out.println(生效日期data.getStr(effectiveDate)条数data.getInt(total));returnnewObject[]{data.getStr(effectiveDate),list};}publicstaticvoidmain(String[]args){Object[]rfetchAll(你的APIKey);if(rnull){return;}JSONArraylist(JSONArray)r[1];for(inti0;ilist.size();i){JSONObjectrowlist.getJSONObject(i);// 注意priceDiesel35 等字段可能为 null取值前判空System.out.printf(%s %s 92#%s 0#柴油%s%n,row.getStr(province),row.getStr(city),row.getStr(priceGas92),row.getStr(priceDiesel0));}}}4.3 Pythonimportrequestsdeffetch_all(api_key:str)-dict: 拉取当前生效批次的全部发改委价格 Returns: dict: {effectiveDate: str|None, total: int, list: [...]}; 失败返回 None resultrequests.get(https://api.xujian.tech/openapi/oilprice/all,headers{X-API-Key:api_key},timeout30,).json()ifresult.get(code)!0:print(拉取失败,result.get(msg))returnNonedataresult[data]print(生效日期,data[effectiveDate],条数,data[total])returndatadefto_price_index(data:dict)-dict:把全量结果整理成 {(省, 市, 区): {油品: 价格}} 的本地索引FIELD{0#柴油:priceDiesel0,-10#柴油:priceDiesel10,-35#柴油:priceDiesel35,92#汽油:priceGas92,95#汽油:priceGas95,98#汽油:priceGas98,}index{}forrowindata[list]:# city / district 为 None 表示上一级统一价用空串占位便于匹配key(row[provinceCode],row.get(cityCode)or,row.get(districtCode)or)prices{}forname,fieldinFIELD.items():valuerow.get(field)ifvalueisnotNone:# 未维护的油品不写进索引prices[name]float(value)index[key]{effectiveDate:row[effectiveDate],prices:prices}returnindexif__name____main__:datafetch_all(你的APIKey)ifdata:idxto_price_index(data)print(索引条数,len(idx))4.4 JavaScriptNode 18asyncfunctionfetchAll(apiKey){constresawaitfetch(https://api.xujian.tech/openapi/oilprice/all,{headers:{X-API-Key:apiKey},});const{code,msg,data}awaitres.json();if(code!0){console.warn(拉取失败,msg);returnnull;}returndata;}// 按省分组方便落库或渲染functiongroupByProvince(list){returnlist.reduce((acc,row){(acc[row.province]||[]).push(row);returnacc;},{});}五、返回示例5.1 成功code 0{code:0,msg:success,data:{effectiveDate:2026-09-24,total:2,list:[{effectiveDate:2026-09-24,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-24 09:00:00},{effectiveDate:2026-09-24,provinceCode:330000,province:浙江省,cityCode:330100,city:杭州市,districtCode:null,district:null,priceDiesel0:7.25,priceDiesel10:7.69,priceDiesel35:null,priceGas92:7.83,priceGas95:8.28,priceGas98:9.32,dataUpdateTime:2026-09-24 09:00:00}],apiCode:oilprice.all,apiName:全量发改委价格查询,chargeType:PER_CALL,balance:94.9900,costMs:12}}5.2 成功但系统暂无数据仍然计费{code:0,msg:success,data:{effectiveDate:null,total:0,list:[],apiCode:oilprice.all,apiName:全量发改委价格查询,chargeType:PER_CALL,balance:94.9900,costMs:5}}code 0但total 0表示系统当前没有维护任何已生效的价格。此时不要把它当成「上次的价格仍然有效」应保留本地缓存并稍后重试。5.3 失败余额不足不扣费{code:500,msg:余额不足请先充值。,data:null}六、典型应用场景6.1 建本地价格库含版本控制用effectiveDate做版本号避免重复入库与重复付费classPriceStore:本地价格库只在生效批次变化时覆盖写入def__init__(self):self.versionNoneself.rows[]defrefresh(self,api_key:str)-bool:datafetch_all(api_key)ifnotdataordata[total]0:returnFalse# 保留旧数据不覆盖ifdata[effectiveDate]self.version:returnFalse# 同一批次无需写入self.versiondata[effectiveDate]self.rowsdata[list]returnTrue6.2 本地匹配查询替代高频调用实时接口拉一次全量后在内存里按「区县 → 市 → 省」回落匹配命中不了再打实时接口deflookup(index:dict,province:str,city:str,district:str)-dict:按 区县 → 市 → 省 逐级回落查找本地价格forkeyin[(province,city,district),(province,city,),(province,,)]:ifkeyinindex:returnindex[key]returnNone这个回落顺序与实时接口内部的匹配规则一致本地复现后行为可预期。6.3 调价日排程配合免费的调价周期接口免费的oilprice.cycle返回当年已登记的调价生效日期列表用它决定何时拉全量fromdatetimeimportdatedefneed_refresh(cycle_dates:list[str],cached_version:str)-bool:todaydate.today().isoformat()past[dfordincycle_datesifdtoday]latestmax(past)ifpastelseNonereturnlatestisnotNoneandlatest!cached_version这样一年只需要在调价日附近调用约 24 次而不是每天一次。6.4 批量对账确认「我算的和基准价一致」把一批历史单据的价格与本地库按effectiveDate对齐重算可快速找出「用了旧价」的异常单据。这也是全量数据相比单条查询最有价值的用法。七、提升可用性的几条实践建议一定要缓存。价格通常约 10 个工作日才变一次每天最多拉一次配合免费的oilprice.cycle能做到只在调价日拉。别写死条数。返回条数取决于维护粒度按total动态处理。油品价格可能是null。按「无价」处理不要当 0否则成本会算成 0。city/district为null是统一价标记不是数据缺失。超时放宽到 20~30 秒。全量响应体比单条查询大别用 5 秒超时。失败时保留旧数据。拉取失败或total 0时不要清空本地库。不要放在用户请求链路上。这是 5 元/次的重接口应走后台定时任务并对任务做幂等同effectiveDate不重复写。不要把它当「实时行情」。这是发改委公布的批次最高零售价不是加油站挂牌价或成交价。八、错误码与排查codemsg示例处理建议0success调用成功total为 0 表示系统暂未维护当前批次价格仍计费500缺少请求头 X-API-Key在请求头补充X-API-Key不扣费500API Key 无效 / API Key 已停用检查 Key 是否正确或在控制台重新启用不扣费500客户不存在或已停用联系平台确认账号状态不扣费500接口不存在或已停用确认oilprice.all当前是否维护中不扣费500余额不足请先充值。可xujian_cq充值后重试余额不足时不扣费。本接口单价较高建议先确认余额九、计费与接入项目说明单价5 元/次取自接口初始化配置后台可调以控制台显示为准计费方式按次计费调用前校验余额行锁 条件式原子扣减不会把余额扣成负数计费时机鉴权通过即扣费total 0的空结果也计费不计费场景Key 缺失/无效、客户停用、接口停用、余额不足建议频率调价日拉取一次其余时间用本地缓存接入流程注册开发者账号 → 控制台创建 API Key → 请求头带上X-API-Key即可调用无需签名或加密。控制台可查看调用量、扣费流水与余额。控制台与在线文档https://api.xujian.tech接口接入、数据与充值相关问题可Vxujian_cq。同系列接口oilprice.realtime实时发改委价格查询0.01 元/次单地区单油品适合高频小查询oilprice.advance提前查询发改委价格按年付费提前 2 小时拿即将生效的新价oilprice.cycle发改委调价周期查询免费用于决定何时拉全量。十、总结全量接口解决的是「一次性把基准价搬回本地」这件事没有参数、没有分页、一次拿全批配合effectiveDate做版本控制就能搭出一份可离线使用的价格库。几个关键取舍值得留意5 元/次鉴权通过即扣费只适合低频批量拉取不适合高频调用更不要放在用户请求链路上空结果也计费系统暂无数据时返回code 0total 0费用照扣所以定时任务要判断total油品价格可能是null与单油品接口的「查不到就报错」不同全量接口用null表示未维护解析时必须判空条数不固定取决于平台维护粒度total才是唯一可信的数字。
