全国油价批量拉取 API一次拿回各省市区六种油品价格要建本地油价库、做全国价格监控大屏、或者给测算模型灌一批基准价逐地区逐个油品去查显然不现实几百次请求、还要自己拼地区清单。oilprice.all就是为这种「一次拉全」场景准备的一个 GET 请求不带任何参数返回当前生效批次下全部地区的价格记录覆盖 0# / -10# / -35# 柴油与 92# / 95# / 98# 汽油共六种油品。需要提醒的是这是按次计费的重接口5 元/次鉴权通过即扣费所以它只适合低频批量同步不适合放在用户请求链路上。接口速览关键事实说明接口地址https://api.xujian.tech/openapi/oilprice/all接口编码oilprice.all请求方式GET无任何 Query 参数鉴权方式请求头X-API-Key不做签名、时间戳或加密业务入参无传了也不生效没有 province / city / limit / 分页返回核心字段effectiveDatelist[]三级地区 六种油品价格计费方式按次计费5 元/次鉴权通过即扣费返回条数当前生效批次的全部记录无分页、无固定上限单次耗时响应体costMs为真实耗时示例 12 毫秒随数据量变化数据口径只返回生效日期 今天的最新批次未来生效的价格不会返回一、哪些业务需要这一步场景具体用法本地油价库建设每次调价后拉一次全量入库本地查询不再依赖接口全国价格监控大屏按省 / 市聚合展示配合调价周期做变化追踪燃油成本模型基准批量导入测算模型按线路匹配各地油价物流全网报价一次拿到所有省市价格生成分区报价模板加油站竞品对标与自有挂牌价逐地区比对找定价偏离数据质检与补全对比本地库发现缺失或过期记录并触发补拉财务毛利测算调价后按新价重算各区域毛利输出敏感性分析行业研究报告按季度留存快照做区域油价差异分析App 离线数据兜底打包进客户端离线包弱网时也能展示基准价跨区运输成本比较同一批货走不同线路时用沿线各地油价算成本差二、请求参数2.1 请求头参数名必填说明X-API-Key是开发者 API Key缺失或无效直接返回失败2.2 业务参数无。接口固定返回当前生效批次的全部启用记录不支持按地区筛选、不支持分页、不支持排序定制。如果你只需要某个地区某一个油品的价格用oilprice.realtime0.01 元/次更划算不要浪费一次全量调用。三、返回字段3.1 顶层与 data字段类型说明codeint0成功非 0 失败统一为500msgString成功为success失败为具体原因dataObject业务数据失败时为nulldata 字段字段类型示例说明effectiveDateString / null2026-09-24本次所取批次的价格生效日期无数据时为nulltotalint2list实际记录数listArray[…]价格明细按省 / 市 / 区县代码升序apiCodeStringoilprice.all接口编码apiNameString全量发改委价格查询接口名称chargeTypeStringPER_CALL本次计费方式balanceBigDecimal94.9900调用完成后的账户余额元costMslong12接口耗时毫秒3.2 list[] 明细字段字段类型示例说明effectiveDateString2026-09-24该行价格的生效日期yyyy-MM-dd当天 0 点生效provinceCodeString500000省级 6 位 adcodeprovinceString重庆市省级名称cityCodeString / null330100地市代码null表示全省统一价cityString / null杭州市地市名称null同上districtCodeString / nullnull区县代码null表示全市统一价districtString / nullnull区县名称null同上priceDiesel0BigDecimal / null7.280# 柴油价格元priceDiesel10BigDecimal / null7.72-10# 柴油价格元priceDiesel35BigDecimal / null8.05-35# 柴油价格元priceGas92BigDecimal / null7.8692# 汽油价格元priceGas95BigDecimal / null8.3195# 汽油价格元priceGas98BigDecimal / null9.3698# 汽油价格元dataUpdateTimeString / null2026-09-24 09:00:00发改委公布 / 运营维护时间yyyy-MM-dd HH:mm:ss3.3 三个必须理解的口径null的价格 ≠ 0 元。某油品字段为null表示该地区没有维护这个油品的价格例如南方多数地区不供应 -35# 柴油展示时应写「暂无」而不是0。地区为null是统一定价。city为null 全省统一价district为null 全市统一价。两者都为null就是省级统一价记录。effectiveDate与dataUpdateTime不是一回事。前者是价格开始生效的日期后者是数据的维护时间判断数据新旧要看dataUpdateTime。内部字段id/status/deleted不对外返回。四、调用示例4.1 curlcurl-shttps://api.xujian.tech/openapi/oilprice/all\-HX-API-Key: 你的APIKey4.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 data 节点失败返回 null鉴权失败不扣费业务失败也已扣费 */publicstaticJSONObjectall(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;}returnjson.getJSONObject(data);}publicstaticvoidmain(String[]args){JSONObjectdataall(你的APIKey);if(datanull){return;}JSONArraylistdata.getJSONArray(list);System.out.println(生效日期data.getStr(effectiveDate)共 list.size() 条);for(inti0;ilist.size();i){JSONObjectrowlist.getJSONObject(i);System.out.printf(%s %s 92#: %s 0#柴油: %s%n,row.getStr(province),row.getStr(city),row.getBigDecimal(priceGas92),row.getBigDecimal(priceDiesel0));}}}4.3 Pythonimportrequestsdefoil_all(api_key:str):返回 data 节点失败返回 Noneresprequests.get(https://api.xujian.tech/openapi/oilprice/all,headers{X-API-Key:api_key},timeout30,)resultresp.json()ifresult.get(code)!0:print(查询失败,result.get(msg))returnNonereturnresult[data]if__name____main__:dataoil_all(你的APIKey)ifdata:print(data[effectiveDate],len(data[list]))4.4 JavaScriptasyncfunctionoilAll(apiKey){constrespawaitfetch(https://api.xujian.tech/openapi/oilprice/all,{headers:{X-API-Key:apiKey}});constresultawaitresp.json();if(result.code!0){thrownewError(result.msg);}returnresult.data;}五、返回示例{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}}当前没有生效批次时不是失败而是空列表仍已扣费{code:0,msg:success,data:{effectiveDate:null,total:0,list:[],apiCode:oilprice.all,apiName:全量发改委价格查询,chargeType:PER_CALL,balance:94.9900,costMs:8}}六、可直接复用的两段代码6.1 落库前归一化把 null 地区还原成统一定价标记defnormalize(rows):把 null 的地区字段转成可落库的标记价格 null 保持 None 不写 0out[]forrinrows:out.append({effective_date:r[effectiveDate],province_code:r[provinceCode],province:r[province],city_code:r[cityCode]or000000,city:r[city]or全省统一价,district_code:r[districtCode]or000000,district:r[district]or全市统一价,price_gas92:r[priceGas92],price_gas95:r[priceGas95],price_gas98:r[priceGas98],price_diesel0:r[priceDiesel0],price_diesel10:r[priceDiesel10],price_diesel35:r[priceDiesel35],data_update_time:r[dataUpdateTime],})returnout6.2 按生效日期做幂等避免重复拉importjsonimportos STATEoil_all_state.jsondefsync_once(api_key:str):同一个 effectiveDate 只写一次库重复执行直接跳过dataoil_all(api_key)ifnotdataornotdata.get(effectiveDate):return0state{}ifos.path.exists(STATE):statejson.load(open(STATE,encodingutf-8))ifstate.get(effective_date)data[effectiveDate]:print(批次未变化跳过)return0rowsnormalize(data[list])# TODO: 写入自己的库json.dump({effective_date:data[effectiveDate],total:len(rows)},open(STATE,w,encodingutf-8))returnlen(rows)七、实践建议必须缓存不要每次业务请求都打。5 元/次的重接口一次调价周期内拉一次即可。不要放在用户请求链路上。走后台定时任务用户侧查本地库。用effectiveDate做幂等。同批次只写一次任务重跑不会产生费用以外的脏数据。先确认价格再决定要不要用。5 元/次不便宜如果你只关心 3 个省份oilprice.realtime0.01 元/次查 3 次更省。价格null不要当 0。展示写「暂无」计算时跳过否则会把成本算成 0。地区null要还原语义。全省统一价 / 全市统一价是展示信息落库时建议写成明确标记而不是留空。响应体可能较大。按市维护时是数百条记录超时建议设到 30 秒客户端按流式或分批处理。配合调价周期接口排程。oilprice.cycle免费用它算出调价日只在调价日当天拉一次全量。八、错误码与排查codemsg是否扣费处理建议0success已扣费调用成功total0表示当前无生效批次500缺少请求头 X-API-Key否在请求头补充X-API-Key500API Key 无效 / API Key 已停用否核对 Key或在控制台重新启用500客户不存在或已停用否联系平台确认账号状态500接口不存在或已停用否确认oilprice.all当前是否维护中500余额不足请先充值否充值后重试余额不足时不扣费计费时机要特别注意本接口先鉴权扣费、再查数据因此参数错误、查不到数据这类情况都已计费。这一点与地址解析、企业查询那类「查不到不收费」的接口不同不要把两套说法混用。九、计费与接入项目说明单价5 元/次计费方式按次计费调用前校验余额采用行锁 条件式原子扣减不会把余额扣成负数计费时机鉴权通过即扣费之后的业务失败不退还不计费场景Key 缺失 / 无效、客户停用、接口停用、余额不足返回条数当前生效批次全部记录无分页接入流程注册开发者账号 → 控制台创建 API Key → 请求头带上X-API-Key即可调用无需签名或加密。控制台可查看调用量、扣费流水与余额。服务站点api.xujian.tech纯文本域名不做跳转。接口试用、数据与充值咨询可在控制台提交工单或 Vxujian_cq。十、小结oilprice.all的定位很清晰用一次较高的成本换一批完整、口径统一的数据。它不适合高频调用但在建库、大屏、批量测算这类场景里比循环调用单地区接口省事得多也更容易保证数据批次一致。使用时要记住四条5 元/次鉴权通过即扣费必须缓存、必须幂等、不能放在用户链路上只返回当前生效批次未来生效的价格查不到想提前拿要用oilprice.advancenull有两种含义地区null是统一定价价格null是未维护都不能当 0没有分页一次返回全部注意响应体大小与超时设置。配套接口oilprice.realtime0.01 元/次单地区单油品、oilprice.cycle免费调价日期列表、oilprice.advance按年付费提前 2 小时拿新价。