物流燃油成本测算 API按线路查各省市当日柴油汽油指导价物流报价、车队预算、工程用油核算最后都会落到一句话这趟活儿烧多少油、油价多少。油价部分如果靠人工查表跨省线路要一个省一个省翻还经常翻到上一轮的价格。oilprice.realtime把这件事做成一次 GET按省 / 市 / 区县 油品名查询返回当前生效的发改委价格带生效日期与数据更新时间可以直接进测算模型。接口速览关键事实说明接口地址https://api.xujian.tech/openapi/oilprice/realtime接口编码oilprice.realtime请求方式GET参数放 Query String鉴权方式请求头X-API-Key不做签名、时间戳或加密必填参数province省名称或 6 位 adcode、oilName6 种油品之一可选参数city、district市 / 区县名称或 adcode返回核心字段oilName/effectiveDate/price 命中地区三级名称与代码计费方式按次计费0.01 元/次鉴权通过即扣费计费时机鉴权通过即扣费之后的业务失败不退还不计费场景Key 缺失 / 无效、客户停用、接口停用、余额不足返回条数固定 1 条单地区单油品数据来源国家发改委公布的成品油最高零售价运营在调价当日维护入库更新频率国家发改委约每 10 个工作日调价一次实际以dataUpdateTime为准单次耗时服务端处理通常个位数毫秒costMs为真实耗时一、哪些业务需要这一步场景具体用法单趟燃油成本核算里程 × 百公里油耗 × 当地柴油价算出这趟活的油钱物流报价单生成报价单附带油价基准与生效日期减少后续争议车队月度预算按常跑线路的各省市油价估算月度燃油预算加油卡结算对账按生效日期核对结算单价避免跨调价日算错工程机械台班成本按项目所在地柴油价测算机械用油成本加油站挂牌参考以发改委最高零售价为基准制定挂牌与优惠策略油价展示物流 App、加油站小程序展示当地当日指导价调价监控大屏多省市价格集中展示配合调价周期做变化追踪补能与出行成本估算按出发地 / 目的地油价估算自驾成本保险理赔参考燃油类损失按当地油价核定赔偿金额二、请求参数2.1 请求头参数名必填说明X-API-Key是开发者 API Key缺失或无效直接返回失败2.2 查询参数参数名必填类型示例说明province是String重庆市 / 500000省名称或 6 位 adcodeoilName是String0#柴油油品中文名取值见下方白名单city否String杭州市 / 330100市名称或 6 位 adcode不传按省级价格匹配district否String西湖区 / 330106区县名称或 6 位 adcode不传按市级价格匹配2.3oilName取值白名单6 种多一个字少一个字都不行0#柴油 -10#柴油 -35#柴油 92#汽油 95#汽油 98#汽油2.4 匹配规则两个容易踩的坑规则说明油品名比对传入值先trim()再精确比对比对失败直接返回错误提示里会带上完整取值列表地区匹配传 6 位纯数字按 adcode 精确匹配传中文按标准行政区划名称精确匹配如重庆市不是「重庆」不做模糊匹配名称对不上不会模糊兜底会一路回落到「查不到」并报错推荐直接传 adcode2.5 地区回落顺序接口先取「当前生效批次」生效日期 今天的最新一批再在该批次内按三级地区匹配省 市 区完全命中 → 返回该区县的价区县没单独定价 → 回落到该市统一价district为null该市也没统一价 → 回落到该省统一价city、district均为null该省按区县分别定价 → 返回该市下辖第一条区县记录兜底 → 返回该省第一条记录。只传province不传city时要小心如果该省按市 / 区县分别定价返回的是该省排序后的第一条记录不等于省会城市的价格也不等于该省均价。要准确就传全city。三、返回字段3.1 顶层与 data字段类型说明codeint0成功非 0 失败统一为500msgString成功为success失败为具体原因dataObject业务数据失败时为nulldata 字段字段类型示例说明oilNameString0#柴油商品名与入参一致effectiveDateString2026-09-24价格生效日期yyyy-MM-dd当天 0 点起生效priceBigDecimal7.28价格元provinceString重庆市命中记录的省名称provinceCodeString500000省级 6 位 adcodecityStringnull地市名称null表示该省是全省统一价cityCodeStringnull地市代码districtStringnull区县名称null表示该市是全市统一价districtCodeStringnull区县代码dataUpdateTimeString2026-09-24 09:00:00数据更新时间yyyy-MM-dd HH:mm:ssapiCodeStringoilprice.realtime接口编码apiNameString实时发改委价格查询接口名称chargeTypeStringPER_CALL本次计费方式balanceBigDecimal99.9900扣费后的账户余额元costMslong6服务端处理耗时毫秒不含公网传输时间3.2 三个字段口径price不会是null。某油品没维护价格时接口直接返回code500而不是返回pricenull。city/district为null是正常结果表示用了上一级统一价展示时可写成「全省统一价」「全市统一价」。effectiveDate与dataUpdateTime一起存。前者判断价格属于哪一批后者判断数据新旧比自己记「上次什么时候拉过」可靠。四、调用示例4.1 curlcurl-s-Ghttps://api.xujian.tech/openapi/oilprice/realtime\--data-urlencodeprovince500000\--data-urlencodeoilName0#柴油\-HX-API-Key: 你的APIKey4.2 JavaHutoolimportcn.hutool.http.HttpRequest;importcn.hutool.json.JSONObject;importcn.hutool.json.JSONUtil;publicclassOilPriceRealtimeClient{privatestaticfinalStringAPI_URLhttps://api.xujian.tech/openapi/oilprice/realtime;/** * 查询某地区某油品的当前生效价格 * * param apiKey 开发者 API Key * param province 省名称或 6 位 adcode * param oilName 油品名如 0#柴油 / 92#汽油 * param city 市名称或 adcode可为空 * return 价格元失败返回 null */publicstaticjava.math.BigDecimalprice(StringapiKey,Stringprovince,StringoilName,Stringcity){HttpRequestreqHttpRequest.get(API_URL).header(X-API-Key,apiKey).form(province,province).form(oilName,oilName).timeout(10000);if(city!null!city.isEmpty()){req.form(city,city);}JSONObjectjsonJSONUtil.parseObj(req.execute().body());if(json.getInt(code)null||json.getInt(code)!0){System.out.println(查询失败json.getStr(msg));returnnull;}returnjson.getJSONObject(data).getBigDecimal(price);}publicstaticvoidmain(String[]args){System.out.println(price(你的APIKey,500000,0#柴油,null));}}4.3 Pythonimportrequestsdefoil_price(api_key:str,province:str,oil_name:str,city:strNone):返回 (price, effective_date)失败返回 Noneparams{province:province,oilName:oil_name}ifcity:params[city]city resprequests.get(https://api.xujian.tech/openapi/oilprice/realtime,paramsparams,headers{X-API-Key:api_key},timeout10,)resultresp.json()ifresult.get(code)!0:print(查询失败,result.get(msg))returnNonereturnresult[data][price],result[data][effectiveDate]if__name____main__:print(oil_price(你的APIKey,500000,0#柴油))4.4 JavaScriptasyncfunctionoilPrice(apiKey,province,oilName,city){constparamsnewURLSearchParams({province,oilName});if(city)params.set(city,city);constrespawaitfetch(https://api.xujian.tech/openapi/oilprice/realtime?${params},{headers:{X-API-Key:apiKey}});constresultawaitresp.json();if(result.code!0){thrownewError(result.msg);}returnresult.data;}五、返回示例全省统一价{code:0,msg:success,data:{oilName:0#柴油,effectiveDate:2026-09-24,price:7.28,province:重庆市,provinceCode:500000,city:null,cityCode:null,district:null,districtCode:null,dataUpdateTime:2026-09-24 09:00:00,apiCode:oilprice.realtime,apiName:实时发改委价格查询,chargeType:PER_CALL,balance:99.9900,costMs:6}}按市定价区县回落到市级统一价{code:0,msg:success,data:{oilName:95#汽油,effectiveDate:2026-09-24,price:8.28,province:浙江省,provinceCode:330000,city:杭州市,cityCode:330100,district:null,districtCode:null,dataUpdateTime:2026-09-24 09:00:00,apiCode:oilprice.realtime,apiName:实时发改委价格查询,chargeType:PER_CALL,balance:99.9800,costMs:9}}失败示例{code:500,msg:未查询到该地区的发改委价格,data:null}{code:500,msg:oilName 取值只能是0#柴油 / -10#柴油 / -35#柴油 / 92#汽油 / 95#汽油 / 98#汽油,data:null}六、可直接复用的两段代码6.1 单趟运输燃油成本deftrip_fuel_cost(api_key:str,distance_km:float,l_per_100km:float,provinces:list,oil_name:str0#柴油):多段线路按各段所在省油价分别计算返回总油费与明细total,detail0.0,[]forprovinprovinces:hitoil_price(api_key,prov,oil_name)ifnothit:continueprice,effhit segdistance_km/len(provinces)/100*l_per_100km*float(price)totalseg detail.append({province:prov,price:price,effective_date:eff,cost:round(seg,2)})returnround(total,2),detail6.2 缓存到「批次」而不是「时间」importjsonimportos CACHEoil_price_cache.jsondefcached_price(api_key:str,province:str,oil_name:str):同一个 (地区, 油品, 生效日期) 只查一次cache{}ifos.path.exists(CACHE):cachejson.load(open(CACHE,encodingutf-8))keyf{province}|{oil_name}hitoil_price(api_key,province,oil_name)ifnothit:returncache.get(key)price,effhitifcache.get(key,{}).get(effective_date)effandpriceincache[key]:returncache[key][price]cache[key]{price:float(price),effective_date:eff}json.dump(cache,open(CACHE,w,encodingutf-8),ensure_asciiFalse)returnprice七、实践建议用 adcode 而不是中文名。名称必须完全匹配标准行政区划名如重庆市传简称会查不到adcode 更稳。传全city。只传省时可能返回该省第一条记录不等于省会价也不等于均价。按批次缓存。以effectiveDate为缓存键同批次不重复调用比按「24 小时过期」更准确。跨调价日要按日期归属。价格当天 0 点生效凌晨的交易要用新价不能按查询时间判断。注意计费时机。本接口鉴权通过即扣费参数写错、地区查不到也已经计费调用前先校验oilName与地区值。price不会是 null。查不到是报错不是返回空值解析时不需要额外判空。不要用它做全国批量。几百个地区逐个查不划算批量场景用oilprice.all5 元/次一次拉全。配合调价周期排程。oilprice.cycle免费用它知道什么时候该刷新价格。八、错误码与排查codemsg是否扣费0success已扣费500缺少请求头 X-API-Key否500API Key 无效 / API Key 已停用否500客户不存在或已停用否500接口不存在或已停用否500余额不足请先充值否500province 不能为空 / oilName 不能为空是鉴权已通过500oilName 取值只能是0#柴油 / -10#柴油 / -35#柴油 / 92#汽油 / 95#汽油 / 98#汽油是500未查询到该地区的发改委价格是500未查询到该地区「xx」的发改委价格是这一条要特别留意本接口与企业查询、地址解析那类「查不到不收费」的接口不同鉴权通过后即使业务失败也不退还。调用前把参数校验做在本地能省掉不少无效扣费。九、计费与接入项目说明单价0.01 元/次计费方式按次计费调用前校验余额采用行锁 条件式原子扣减不会把余额扣成负数计费时机鉴权通过即扣费之后的业务失败不退还不计费场景Key 缺失 / 无效、客户停用、接口停用、余额不足返回条数固定 1 条单地区单油品接入流程注册开发者账号 → 控制台创建 API Key → 请求头带上X-API-Key即可调用无需签名或加密。控制台可查看调用量、扣费流水与余额。服务站点api.xujian.tech纯文本域名不做跳转。接口试用、数据与充值咨询可在控制台提交工单或联系 Vxujian_cq。十、小结对物流、车队、工程用油这类场景来说油价数据的难点不是「查到」而是查得准、知道它属于哪一批、并且别在错误的时候刷新。oilprice.realtime一次一分钱把这三个问题都解决了价格精确到市 / 区县并且明确告诉你用了哪一级统一价city/district为null带生效日期与更新时间可以按批次缓存、按日期归属固定返回 1 条解析简单price不会是 null。四个配套接口按需选用oilprice.all5 元/次一次拉全国、oilprice.cycle免费调价日期列表、oilprice.advance按年付费提前 2 小时拿新价。