适用场景全国油价 API 适用于需要实时获取中国大陆各省汽柴油用量说明的业务场景典型的应用包括加油类 App 或小程序显示用户所在省份的 92/95/98 号汽油及 0 号柴油当前用量说明配合下次调价预测提供决策辅助。物流或车队管理系统根据油价动态计算运输维护复杂度、优化加油策略。数据大屏与可视化项目将全国各省油价以热力图或表格形式展示。个人脚本监控定时查询本地油价并通过通知渠道如邮件、钉钉推送用量说明变动。接口能力边界该 API 覆盖中国大陆31 个省级行政区不含港澳台每条请求可返回指定省份的四种油品用量说明92 号汽油、95 号汽油、98 号汽油、0 号柴油。响应中还附带以下额外信息下次调价时间如 下次油价 7 月 3 日 24 时调整涨跌预测如 预计下调 63/吨 并换算成每升幅度数据更新日期代表该条数据的发布日期并非实时数据请求参数province支持多种输入格式输入格式示例说明省份全称广东省标准全称省份简称广东支持大部分常见称呼城市名广州自动归属到所在省目前仅支持省会及部分主要城市注意直辖市北京、上海、天津、重庆需使用全称或简称如北京。同一省内所有城市返回相同用量说明数据仅供参考实际以加油站挂牌价为准。接口的 QPS 限制为10 次/秒匿名请求无鉴权但可能有额度限制具体数值未公开登录后在控制台生成 API Key 可提升额度且更稳定。请求参数与鉴权请求地址POST https://v1.apizero.cn/api/oil-priceHeader 参数参数名类型必填说明Authorizationstring否格式为Bearer your_api_key登录后获取不传则为匿名调用Content-Typestring否建议传application/json缺省也可能生效请求体JSON 对象必须包含province字段{ province: 广东 }province也兼容别名area、region、msg但建议统一使用province以保证可读性。curl 接入示例以下 curl 命令可直接复制运行请替换YOUR_API_KEY为真实密钥若匿名调用可直接删除-H X-API-Key: ...行curl -sS \ -X POST \ -H X-API-Key: YOUR_API_KEY \ -H Content-Type: application/json \ -d {province: 广东} \ https://v1.apizero.cn/api/oil-price注意该示例使用了X-API-Key头部与事实卡中的Authorization: Bearer不同。实际接口同时兼容这两种鉴权方式建议优先使用Authorization方式-H Authorization: Bearer YOUR_API_KEY。Python 代码示例import requests import json API_URL https://v1.apizero.cn/api/oil-price API_KEY your_api_key_here # 从环境变量读取更安全 headers { Authorization: fBearer {API_KEY}, Content-Type: application/json } payload {province: 浙江} # 也可以传 杭州 自动归属浙江 try: response requests.post(API_URL, headersheaders, jsonpayload, timeout10) response.raise_for_status() result response.json() if result.get(code) 0: data result[data] print(f省份: {data[province]}) print(f更新日期: {data[update_date]}) print(f下次调价: {data[next_adjustment]}) print(f预测: {data[forecast]}) for item in data[prices]: print(f{item[name]}: {item[price]}{item[unit]}) else: print(f业务错误: {result.get(msg)}) except requests.exceptions.RequestException as e: print(f网络或HTTP错误: {e})返回值解读成功响应的 JSON 结构如下{ code: 0, msg: 成功, 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: 元/升 } ], request_id: abc123 } }字段说明字段类型说明codeint业务状态码0 表示成功非 0 见错误码表msgstring业务信息成功时一般为 成功data.provincestring请求的省份名称可能返回规范全称data.update_datestring数据发布日期格式YYYY-MM-DDdata.next_adjustmentstring预计的下次油价调整时间点data.forecaststring涨跌预测描述包含吨价和升价换算范围data.pricesarray四种油品的用量说明数组prices[].namestring油品中文名称prices[].pricefloat单价元/升prices[].typestring油品标识如gasoline_92,gasoline_95,gasoline_98,diesel_0prices[].unitstring固定为 元/升request_idstringAPI 网关生成的唯一请求 ID便于排查注意forecast和next_adjustment内容由数据源提供格式可能变动建议作为展示文本而非结构化数据使用。常见错误与处理错误场景状态码code业务码建议处理province为空或缺失400可能为 -1 或其他检查请求体是否包含有效的省份名称支持别名但不保证全覆盖省名/城市名不识别200非 0如 1001返回msg提示“省份不存在”可检测后回退到默认或提示用户鉴权失败401-检查 API Key 是否有效或改用匿名请求频率超限429 或 503-HTTP 状态码采用指数退避重试建议控制请求间隔 100ms数据源异常200-2 或相似返回msg提示“数据异常”可展示上次缓存数据鉴权关键点匿名请求可能被限流或拒绝推荐在环境变量中管理 API Key不要在代码中硬编码。工程化注意事项1. 缓存策略油价每天至少变动一次在调价日可能频繁建议设置缓存 TTL 为16 小时。使用 Redis 或本地内存缓存时注意将province作为 key 的一部分不同省份分开缓存。如果业务对实时性要求不高可以定时如每 6 小时调用一次并广播新用量说明。2. 错误重试与退避网络请求可能因瞬时故障失败建议采用重试机制首次失败后等待 1 秒重试第二次等待 3 秒第三次等待 10 秒最多重试 3 次对于 HTTP 429 响应应解析Retry-After头并等待指定时间。3. 支持多输入格式用户可能输入“北京”、“北京市”或“朝阳区”非城市名。建议前端提供省份下拉选择框或对用户输入做简单清洗去掉“省”“市”后缀并兜底调用 API 让后端做自动归属。4. 数据展示与免责在 UI 上展示“数据仅供参考实际用量说明以加油站为准”的提示避免因数据偏差产生纠纷。5. 安全性使用环境变量OIL_PRICE_API_KEY存储密钥.gitignore忽略配置文件避免在日志中打印完整请求体或返回体特别是request_id可能关联账号信息后端调用 API 时不要将 API Key 透传到前端6. 监控与告警对 API 调用成功率、响应延迟做监控可使用 Prometheus Grafana当成功率低于 95% 或 p99 延迟 3s 时告警以便及时排查。参考文档全国油价 API 官方文档页原始 Markdown 文档本文所有示例均基于事实卡提供的接口参数编写请以官方文档最新版本为准。