全国油价 API 接入指北：请求参数、返回结构与容错设计

写在前面油价数据的获取频率通常不高每日更新但接入方往往有跨省对比、定时抓取等需求。全国油价接口以 POST 方式提供查询能力支持按省份简称/全称查询也能把常见城市名自动归属到所在省份。本文只讲接入过程中真正需要关心的部分参数边界、返回结构、异常排查以及接入后如何把数据落到工程里。适用场景与能力边界在接入前先明确接口能做什么、不能做什么。适用场景资讯类应用展示各省当日汽柴油零售限价物流/货运系统按省份追踪油价波动内部数据看板每日拉取一次做涨跌预测展示城市名转省份后再查询减少用户输入维护复杂度能力边界覆盖范围为 31 个大陆省级行政区仅返回省级维度的用量说明同一省内各城市油价一致数据为零售限价实际用量说明以当地加油站为准返回字段中包含预测文案和下次调价时间但预测仅作参考接口 QPS 上限为 10 次/秒不适合做高频轮询请求参数详解Header 参数参数名必填类型说明Authorization否stringBearer 你的API Key登录调用可提升额度匿名可不传Content-Type否string请求体格式传application/json即可注意素材中的 curl 示例使用X-API-Key头传密钥而 Header 参数表里写的是Authorization。实际接入时以文档页 https://apizero.cn/aidocs/oil-price 的说明为准。稳妥做法是两个头都带上服务端按文档约定的优先级读取。请求体字段请求体是一个 JSON 对象核心字段如下字段名必填类型说明province是string省/直辖市/自治区名称支持简称或全称如广东、广东省、内蒙古也支持常见城市名如广州自动归属到广东接口还兼容area、region、msg作为province的别名。这意味着如果上游系统已经用了region字段传参可以少做一层字段映射。{ province: 广东 }{ region: 广州 }两种写法等价。边界情况传河北或河北省都能命中同一个省份传内蒙古不要省略为内蒙以实际支持范围为准传不在 31 个省级行政区内的名称如香港、台湾返回结果以接口文档说明为准传空字符串或缺失province时大概率触发参数校验错误curl 接入示例下面是一个完整的 curl 调用将APIZERO_API_KEY替换为你自己的密钥即可curl -sS \ -X POST \ -H X-API-Key: $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {province: 广东} \ https://v1.apizero.cn/api/oil-price如果采用 Bearer 方式curl -sS \ -X POST \ -H Authorization: Bearer $APIZERO_API_KEY \ -H Content-Type: application/json \ -d {province: 江苏} \ https://v1.apizero.cn/api/oil-priceJava 接入示例实际项目中很少直接拼 HTTP 请求更多是封装一个客户端类。下面是一个基于 Java 11 原生 HttpClient 的示例不依赖第三方库import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.time.Duration; public class OilPriceClient { private static final String API_URL https://v1.apizero.cn/api/oil-price; private final HttpClient httpClient; private final String apiKey; public OilPriceClient(String apiKey) { this.apiKey apiKey; this.httpClient HttpClient.newBuilder() .connectTimeout(Duration.ofSeconds(5)) .build(); } public String queryProvince(String province) throws Exception { String body {\province\:\ province \}; HttpRequest request HttpRequest.newBuilder() .uri(URI.create(API_URL)) .timeout(Duration.ofSeconds(10)) .header(Content-Type, application/json) .header(X-API-Key, apiKey) .header(Authorization, Bearer apiKey) .POST(HttpRequest.BodyPublishers.ofString(body)) .build(); HttpResponseString response httpClient.send(request, HttpResponse.BodyHandlers.ofString()); return response.body(); } }调用方式OilPriceClient client new OilPriceClient(your-api-key); String result client.queryProvince(广东); System.out.println(result);工程中使用时建议再包一层 JSON 解析将响应转换为 POJO便于后续字段读取。响应结构解读成功响应的 JSON 结构如下{ code: 0, msg: 成功, request_id: abc123, data: { province: 广东, update_date: 2026-06-20, next_adjustment: 下次油价7月3日24时调整, forecast: 预计下调630元/吨(0.48元/升-0.57元/升), prices: [ { name: 92号汽油, type: gasoline_92, price: 7.96, unit: 元/升 }, { name: 95号汽油, type: gasoline_95, price: 8.62, unit: 元/升 }, { name: 98号汽油, type: gasoline_98, price: 10.62, unit: 元/升 }, { name: 0号柴油, type: diesel_0, price: 7.62, unit: 元/升 } ] } }字段说明字段类型说明codenumber业务状态码0 表示成功msgstring状态描述request_idstring请求 ID排障时可用data.provincestring实际命中的省份名称data.update_datestring数据更新日期data.next_adjustmentstring下次调价时间文案data.forecaststring后续涨跌预测文案data.prices[]array各油品用量说明列表prices[].namestring油品显示名称prices[].typestring油品类型标识如gasoline_92prices[].pricenumber单价单位见unitprices[].unitstring用量说明单位固定为元/升字段使用建议展示油价时优先用name字段type用于前端区分图标或排序update_date不一定等于当天日期缓存策略应以它为准forecast是文本字段直接展示即可不要尝试解析其中的数字prices数组的长度和顺序在文档未承诺固定不要按下标硬编码读取常见错误排查以下是根据接口特征总结的几类高频问题1. 返回 4xx 或业务码非 0大概率是参数问题province传了空字符串省份名称不在支持列表内JSON 格式错误比如多了尾逗号或单引号建议在调用前做一次本地校验对省份名做白名单过滤避免无效请求打到线上。2. 返回 401 或 403鉴权失败。检查API Key 是否正确Header 用的是X-API-Key还是Authorization: Bearer以文档页为准是否有匿名调用次数限制3. 返回 429 或提示限流接口 QPS 为 10 次/秒遇到限流时退避重试建议指数退避初始间隔 1 秒本地加缓存同一省份短时间内不要重复请求批量省份查询改为定时任务串行执行4. 数据对不上确认查询的是省份还是城市名城市名会自动归省如果同名城市较多需要确认归属是否符合预期update_date可能不是当天展示时明确标注数据日期工程化注意事项缓存策略油价一天只更新一次没必要每次进入页面都请求远程接口。推荐做法以update_date为缓存键按天失效31 个省份可以做成全量缓存每天定时拉取一次缓存中间件用 Redis 或本地 Caffeine 均可数据量很小限流与重试QPS 10 的额度对个人应用来说足够但要防止代码里的循环调用把额度打满// 错误示例for 循环里同步调用瞬间打满 QPS for (String province : provinces) { String result client.queryProvince(province); // process... }正确做法是分批拉取控制请求间隔for (int i 0; i provinces.size(); i) { String result client.queryProvince(provinces.get(i)); // process... if (i provinces.size() - 1) { Thread.sleep(200); // 控制频率避免触发限流 } }请求唯一性问题request_id字段建议记入日志。排查问题时凭request_id向服务端确认本次请求的具体处理情况比贴一整段响应体更高效。数据展示规范页面展示时要标注update_date避免用户误以为是实时用量说明对forecast字段加一个“预测”前缀与当前用量说明做视觉区分接口返回的是零售限价不是实际成交价面向 C 端展示时建议加免责说明参考文档文档页https://apizero.cn/aidocs/oil-price原始文档https://apizero.cn/aidocs/oil-price/raw.md