一、适用场景全国油价接口适用于需要实时获取各省份汽柴油零售用量说明的场景典型应用包括油价展示 App / 小程序为用户提供所在省的当日油价信息。出行维护复杂度估算结合路线规划计算燃油费用。行业数据分析跟踪油价变化趋势辅助决策。车主社区 / 导航软件嵌入油价查询功能提升用户体验。本教程围绕“最小可运行示例”展开让开发者用最少的代码快速获得可解析的结果。二、接口能力边界项目说明接口名称全国油价请求方法POST请求地址https://v1.apizero.cn/api/oil-price覆盖范围大陆 31 个省级行政区返回油品92# / 95# / 98# 汽油、0# 柴油数据更新每日更新返回 update_date 字段调价预测返回下次调价日期和涨跌预测forecast地区别名支持省份简称/全称也兼容城市名自动归属到所在省QPS 限制10 次/秒以实际文档为准需要注意接口返回的是发改委规定的零售限价即“最高零售价”实际加油站可能略有浮动数据仅供估算参考。三、请求参数与鉴权3.1 HTTP 方法及 URL使用POST方法请求地址固定https://v1.apizero.cn/api/oil-price3.2 请求头HeadersContent-Type: application/json必需Authorization: Bearer 你的 API Key可选匿名亦可调用但带 Key 可提升调用额度3.3 请求体Body格式为 JSON 对象包含一个必填字段province。{ province: 广东 }支持别名area、region、msg均可视为等同province。也支持传入城市名如“广州”会自动归并到“广东”。四、最小可运行示例curl以下命令可直接在终端执行请替换${APIZERO_API_KEY}为你的实际 Key若不传 Key 则删除该 Header 行curl -sS \ -X POST \ -H Authorization: Bearer ${APIZERO_API_KEY} \ -H Content-Type: application/json \ -d {province: 广东} \ https://v1.apizero.cn/api/oil-price预期输出片段实际返回会包含完整 JSON{ code: 0, data: { province: 广东, update_date: 2026-06-20, next_adjustment: 下次油价7月3日24时调整, forecast: 预计下调630元/吨(0.48元/升-0.57元/升), prices: [ {name: 92号汽油, price: 7.96, type: gasoline_92, unit: 元/升}, {name: 95号汽油, price: 8.62, type: gasoline_95, unit: 元/升}, {name: 98号汽油, price: 10.62, type: gasoline_98, unit: 元/升}, {name: 0号柴油, price: 7.62, type: diesel_0, unit: 元/升} ] }, msg: 成功, request_id: abc123 }若不带 API Key只需移除-H Authorization: ...这行即可。五、最小可运行示例Python以下 Python 脚本使用requests库需提前安装pip install requests实现同样的最小调用import requests import json # 配置匿名调用则 api_key 设为 None API_URL https://v1.apizero.cn/api/oil-price API_KEY your_api_key_here # 替换或设为 None PROVINCE 广东 headers {Content-Type: application/json} if API_KEY: headers[Authorization] fBearer {API_KEY} payload {province: PROVINCE} try: resp requests.post(API_URL, headersheaders, jsonpayload, timeout10) resp.raise_for_status() data resp.json() if data.get(code) 0: prices data[data][prices] print(f省份: {data[data][province]}) print(f更新日期: {data[data][update_date]}) print(f下次调价: {data[data][next_adjustment]}) print(f涨跌预测: {data[data][forecast]}) print(--- 油价列表 ---) for item in prices: print(f{item[name]}: {item[price]} {item[unit]}) else: print(fAPI 返回错误: {data.get(msg)}) except requests.exceptions.RequestException as e: print(f请求异常: {e})运行结果示例省份: 广东 更新日期: 2026-06-20 下次调价: 下次油价7月3日24时调整 涨跌预测: 预计下调630元/吨(0.48元/升-0.57元/升) --- 油价列表 --- 92号汽油: 7.96 元/升 95号汽油: 8.62 元/升 98号汽油: 10.62 元/升 0号柴油: 7.62 元/升此脚本无需额外依赖仅requests完整覆盖了从请求到解析的流程是典型的“最小可运行示例”。六、返回字段解读响应体为 JSON 对象根字段说明字段类型说明codeint状态码0 表示成功非零表示错误msgstring状态描述成功时返回“成功”request_idstring请求唯一标识用于排查日志dataobject核心数据对象data字段详解字段类型说明provincestring查询的省份标准化后的名称update_datestring数据更新日期格式YYYY-MM-DDnext_adjustmentstring下次油价调整时间说明forecaststring下次调整的涨跌预测元/吨 和 元/升估算范围pricesarray包含四种油品的用量说明对象列表prices[]每个元素字段字段类型示例说明namestring92号汽油油品名称中文typestringgasoline_92油品类型编码pricenumber7.96用量说明数值unitstring元/升用量说明单位注意forecast中的 “下调63/吨(0.48元/升-0.57元/升)” 是一个描述性字符串客户端若需结构化使用建议自行解析因为格式可能随政策说明变化。七、常见错误与排查7.1 HTTP 状态码 400原因请求体未提供province或 province 值为空/无效。解决确保 body 包含{province: 某省}省名不能为空。7.2 HTTP 状态码 401原因Authorization Header 格式错误或 API Key 无效。解决若使用 Key请检查Bearer前缀和 Key 本身匿名调用则直接删除该 Header。7.3 HTTP 状态码 429原因请求频率超过 QPS 限制10次/秒。解决在代码中加入重试逻辑或控制请求间隔不小于 100ms。7.4 HTTP 状态码 500原因服务端异常。可能是临时故障或参数问题。解决稍后重试同时检查请求体是否正确。7.5 返回 code 非 0原因API 业务错误具体看msg字段。解决检查 province 是否在支持的省份列表中31个大陆行政单位。八、工程化注意事项8.1 缓存策略油价数据每日更新一次且更新时间为白天具体以官方为准。前端应用应至少缓存至当天结束避免频繁请求。建议使用内存缓存或 Redis设置 TTL 为 4~6 小时并留一个手动刷新按钮。8.2 错误重试与退避对于 429 或 5xx 错误应实现指数退避重试例如 1s、2s、4s 间隔最多重试 3 次。不要对 4xx 业务错误重试以免浪费配额。8.3 地区输入规范化用户可能输入简称“粤”、全称“广东省”、城市名“广州”。接口已内置别名解析但输入建议仍可做前端预处理将常见城市名映射到省份或直接提示用户输入省份名称。8.4 数据可靠性声明接口返回的是发改委指导价最高零售限价实际油价以当地加油站为准。如果用于生产环境建议在界面上附加“数据仅供参考”的声明。8.5 安全与凭证管理API Key 不应硬编码在客户端代码中。后端服务调用时建议使用环境变量并定期轮换。匿名调用虽不传 Key但调用额度可能较低生产环境建议准备 Key 并使用。参考文档全国油价 API 官方文档原始 Markdown 文档