全国油价查询接口接入实战：参数设计、调用示例与常见问题

全国油价查询接口面向车主服务、汽车资讯与民生数据类应用，提供全国 31 个省份汽油、柴油各标号油价的结构化数据。接口以标准 REST 风格提供 GET 调用，返回 JSON 格式，数据依据国家公布的调价信息每日 07:00 同步刷新。本文将完整覆盖接入流程、参数设计、多语言调用示例、返回结构解读、调用限制与工程实践，供开发者直接参考落地。

一、技术简介

全国油价查询接口（下文称「油价接口」）将各省汽柴油零售数值聚合为一份结构化的数据源，调用方可按省份维度获取对应标号油品数值，或一次性拉取全国 31 省全量油价用于对比展示。

接口特性：

• 单一端点，GET 方法，无请求体，调用门槛低；
• 返回 JSON，字段扁平化（prov、各油品标号、更新时间 ct），便于直接绑定前端模板；
• 数据每日 07:00 刷新一次，反映国家最新公布的调价结果；
• 鉴权采用 APPCODE 简单身份认证，无需计算签名。

二、能力概览

油价接口覆盖的油品标号与返回内容如下，调用方据此设计展示层：

说明：不同省份实际销售的油品标号略有差异，部分标号在该省可能无对应数值，返回中相应字段为空或省略，前端需做空值兜底。

三、适用场景

• 车主服务类 APP / 小程序：展示「今日油价」卡片，支持按所在地省份定位；
• 汽车资讯网站 / 公众号：每日油价播报，全国对比榜单；
• 出行成本估算工具：按目的地省份计算油费参考区间；
• 数据看板 / BI：接入多日历史缓存，绘制油价走势与涨跌分析。

四、接入流程

接入分为五步：

1. 开通服务：在云市场完成商品开通，获取鉴权信息（APPCODE）；
2. 获取鉴权：拿到该应用对应的 APPCODE，用于请求头认证；
3. 构造请求：按下方参数表拼接 GET 请求，Authorization: APPCODE <apptoken>；
4. 解析返回：读取 showapi_res_body.list，按省份与标号绑定数据；
5. 本地缓存：结合 ct 更新时间做每日缓存，避免重复请求。

五、调用示例与返回结构

请求参数（Query）：

请求头：

调用端点（以控制台实际分配的调用地址为准）：

GET /todayoil?prov=广西
Authorization: APPCODE <apptoken>

成功返回示例（完整结构）：

{
   
  "showapi_res_code": 0,
  "showapi_res_error": "",
  "showapi_res_body": {
   
    "ret_code": 0,
    "list": [
      {
   
        "prov": "天津",
        "p90": "6.01",
        "p0": "6.09",
        "p95": "6.84",
        "p97": "6.84",
        "p89": "5.48",
        "p92": "6.48",
        "p93": "6.48",
        "ct": "2026-09-14 07:00:00"
      },
      {
   
        "prov": "新疆",
        "p90": "5.78",
        "p0": "5.52",
        "p95": "6.93",
        "p97": "6.45",
        "p89": "6.06",
        "p92": "6.41",
        "p93": "5.97",
        "ct": "2026-09-14 07:00:00"
      }
    ]
  }
}

顶层 showapi_res_code 为 0 表示网关调用成功；showapi_res_body.ret_code 为 0 表示业务数据正常。两层判断缺一不可。

多语言调用示例

Python：

import requests

url = "/todayoil"
headers = {
   "Authorization": "APPCODE <你的apptoken>"}
params = {
   "prov": "广西"}
resp = requests.get(url, headers=headers, params=params, timeout=10)
data = resp.json()
if data["showapi_res_code"] == 0 and data["showapi_res_body"]["ret_code"] == 0:
    for item in data["showapi_res_body"]["list"]:
        print(item["prov"], item["p92"], item["p95"], item["p0"])

Node.js：

const url = new URL("/todayoil");
url.searchParams.set("prov", "北京");
const resp = await fetch(url, {
   
  headers: {
    Authorization: "APPCODE <你的apptoken>" },
});
const data = await resp.json();
const rows = data.showapi_res_body?.list ?? [];
rows.forEach((r) => console.log(r.prov, r.p92, r.p95, r.p0));

Java：

// 省略 HTTP 客户端初始化，示意参数拼装与双层判断
Map<String, String> query = new HashMap<>();
query.put("prov", "上海");
// GET /todayoil?prov=上海  Authorization: APPCODE <你的apptoken>
if (resCode == 0 && body.ret_code() == 0) {
   
    body.list().forEach(r ->
        System.out.println(r.prov() + " " + r.p92() + " " + r.p95()));
}

PHP：

$ch = curl_init('https://your-endpoint/todayoil?prov=四川');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 10,
    CURLOPT_HTTPHEADER     => ['Authorization: APPCODE 你的apptoken'],
]);
$out   = curl_exec($ch);
$data  = json_decode($out, true);
$ok    = ($data['showapi_res_code'] ?? -1) === 0
      && ($data['showapi_res_body']['ret_code'] ?? -1) === 0;

六、在线调试实录

以控制台在线调试为例，请求 GET /todayoil（不传 prov）：

• 请求：Authorization: APPCODE <apptoken>，Query 为空；
• 响应：showapi_res_code = 0，list 返回 31 条省级记录；
• 单条记录包含省份名、各油品标号、更新时间 ct；
• 响应耗时约几十毫秒量级，便于在调试面板快速验证鉴权与参数是否正确。

调试时建议：先传一个省份验证字段完整，再去掉 prov 验证全量返回，确认两种形态都符合预期。

七、调用限制与规范

配额与限流阈值为账户级配置，请以控制台当前显示为准；本文不保证具体数字长期有效。

八、工程实践与合规

• 结果缓存：油价日内恒定，可用 ct 作为缓存键，命中当天缓存则不再请求，减少配额消耗；
• 幂等与重试：GET 请求天然幂等，失败可按指数退避重试；鉴权失败（showapi_res_code 非 0 且提示认证问题）不应盲目重试；
• 熔断降级：连续失败触发熔断，展示上一次成功快照并标注数据时间；
• 前端兜底：油品标号字段可能缺失，渲染前做空值判断，避免「undefined」暴露；
• 数据安全：油价为公开民生数据，无需脱敏；若结合用户定位，应在用户告知与最小必要原则下使用；
• 合规边界：数据仅供展示参考，不构成对加油成本、出行决策的业务承诺。

九、错误码排查

十、技术 FAQ

油价接口支持按省份查询吗？支持。传 prov=省份名 返回该省记录；不传则返回全国 31 省。

数据多久更新一次？每日 07:00 刷新一次，返回中的 ct 字段标明当前数据时间。

鉴权方式是什么？采用 APPCODE 简单身份认证，请求头 Authorization: APPCODE <apptoken>，无需签名计算。

返回的油品数值单位是什么？元/升，字段为字符串类型，参与数值计算时需自行转 float。

为什么有些省份缺少某标号？不同省份实际流通的油品标号不同，接口如实返回该省可用标号，缺失字段前端需兜底。

调用失败会扣减配额吗？通常仅 HTTP 200 的成功响应扣减次数，非 200 不扣费，具体以控制台规则为准。

可否用于小程序 / APP？可以。返回为轻量 JSON，直接绑定前端模板即可用于油价卡片、榜单、走势等场景。

十一、内容小结

油价接口以单一 GET 端点提供全国 31 省汽柴油各标号的结构化数据，鉴权简单、返回扁平、日内缓存友好，适合快速集成到车主服务、资讯与成本估算类应用。接入时关注两点：一是 showapi_res_code 与 ret_code 的双层判断，二是结合 ct 做每日缓存以降低无效调用。工程上补充空值兜底、退避重试与熔断降级，即可稳妥上线。