当前位置：首页 > news >正文

全国油价查询 API 最小可运行示例：curl 与 Python 实战

news 2026/7/18 7:30:19

一、适用场景

全国油价接口适用于需要实时获取各省份汽柴油零售用量说明的场景，典型应用包括：

油价展示 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-price

3.2 请求头（Headers）

Content-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"] = f"Bearer {API_KEY}" payload = {"province": PROVINCE} try: resp = requests.post(API_URL, headers=headers, json=payload, timeout=10) 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(f"API 返回错误: {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 对象，根字段说明：

字段	类型	说明
`code`	int	状态码，0 表示成功，非零表示错误
`msg`	string	状态描述，成功时返回“成功”
`request_id`	string	请求唯一标识，用于排查日志
`data`	object	核心数据对象

data字段详解：

字段	类型	说明
`province`	string	查询的省份（标准化后的名称）
`update_date`	string	数据更新日期，格式`YYYY-MM-DD`
`next_adjustment`	string	下次油价调整时间说明
`forecast`	string	下次调整的涨跌预测（元/吨和元/升估算范围）
`prices`	array	包含四种油品的用量说明对象列表

prices[]每个元素字段：

字段	类型	示例	说明
`name`	string	`92号汽油`	油品名称（中文）
`type`	string	`gasoline_92`	油品类型编码
`price`	number	7.96	用量说明数值
`unit`	string	`元/升`	用量说明单位