全国油价接口能力边界解析：省份映射、返回结构与限流设计
接口定位：能做什么，不能做什么
全国油价 API 是一个面向生活服务场景的轻量级数据接口，通过一次 POST 请求即可查询全国 31 个大陆省级行政区的汽柴油零售限价。它并不提供加油站级别的精确用量说明，也不提供历史用量说明走势或国际原油行情，而是聚焦于「今日各省官方零售限价 + 下一次调价时间 + 涨跌预测」这一信息集合。
从数据组织方式来看，接口将用量说明按行政区域归并：同省内各城市油价一致。这意味着它适合做区域维度的用量说明展示、出行维护复杂度估算、行业数据采集等场景，但若需要精确到街道或加油站的实时用量说明，这个接口并不适用。
适用场景分析
驾驶维护复杂度估算类应用
在车辆导航、物流调度或出行规划类应用中，油价是一个影响决策的动态变量。通过该接口定期拉取省份维度的用量说明数据，可以在地图上渲染区域油价分布，或结合里程计算预估燃油维护复杂度。
行业数据监控与报表
对于物流公司、运输平台或油价分析类工具，需要按省份追踪油价变动趋势。接口返回的update_date和next_adjustment字段可以帮助判断数据的时效性，forecast字段则提供下一次调价的预测信息，便于提前调整运营策略。
内容型应用的附属功能
资讯类 App 或公众号可以在文章底部附加油价信息卡片。由于接口数据量小（单次请求仅返回数 KB），非常适合低频轮询场景，例如每小时或每天同步一次到本地缓存。
接口能力边界：省份映射与请求参数
请求方式与地址
接口使用 POST 方法，请求地址固定为：
https://v1.apizero.cn/api/oil-price所有查询参数放在请求体中，采用 JSON 格式。单接口 QPS 限制为 10 次/秒，即每 100 毫秒最多允许 10 个并发请求，超过限制会被拒绝或限流。
请求体参数说明
请求体必须是一个 JSON 对象，包含一个查询字段。字段细节如下：
| 参数名 | 类型 | 必填 | 说明 |
|---|---|---|---|
province | string | 是 | 省/直辖市/自治区名称，支持简称、全称以及常见城市名；兼容别名area/region/msg |
关于province字段，有几个值得注意的细节：
- 支持「广东」「广东省」两种写法；
- 支持直辖市名称如「北京」「上海市」；
- 支持常见城市名自动归属，例如「广州」会被解析为广东；
- 内蒙古等自治区同时支持简称与全称；
- 若传入无法识别的名称，接口会返回错误码而不是猜测性匹配。
这种灵活的入参设计降低了调用方的参数标准化维护复杂度，但依赖调用方对输入值做基本的合法性校验，因为城市名到省份的归属规则并不对外公开。
鉴权方式
接口支持匿名调用，也支持通过 Header 传递 API Key 来获得更高额度。素材中给出的 curl 示例使用了X-API-Key请求头：
X-API-Key: $APIZERO_API_KEY在文档的 Header 参数表中，鉴权字段被标记为Authorization: Bearer <你的 API Key>。两种方式以官方文档为准，建议在代码中统一从环境变量读取密钥，避免硬编码。
最低可运行请求体
最简单的合法请求体如下：
{ "province": "广东" }若使用别名area，则请求体变为：
{ "area": "四川" }接入示例：curl 与 Python
curl 直接调用
以下是一个完整的 curl 请求，传入省份全称：
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"执行后将返回 JSON 格式的油价数据。需要注意：$APIZERO_API_KEY是环境变量，若未设置，可在命令行中直接替换为实际 Key 字符串。
Python 请求示例
使用requests库实现同样的调用：
import os import requests url = "https://v1.apizero.cn/api/oil-price" payload = { "province": "浙江" } headers = { "X-API-Key": os.environ.get("APIZERO_API_KEY", ""), "Content-Type": "application/json" } resp = requests.post(url, json=payload, headers=headers, timeout=10) data = resp.json() if data.get("code") == 0: prices = data["data"]["prices"] for item in prices: print(f"{item['name']}: {item['price']} {item['unit']}") print(f"更新日期: {data['data']['update_date']}") print(f"下一次调价: {data['data']['next_adjustment']}") else: print(f"请求失败: {data.get('msg')}")这段代码通过env获取 API Key，在匿名条件下传入空字符串即可。超时时间建议设置 10 秒，避免极端网络情况下请求长时间挂起。
返回字段逐项解读
顶层结构
成功响应包含code、msg、data、request_id四个字段：
| 字段 | 类型 | 说明 |
|---|---|---|
code | number | 业务状态码，0表示成功 |
msg | string | 状态描述，成功时为「成功」 |
data | object | 油价数据主体 |
request_id | string | 请求追踪标识，便于排查问题 |
data 对象
data中包含 5 个关键子字段：
{ "province": "广东", "update_date": "2026-06-20", "next_adjustment": "下次油价7月3日24时调整", "forecast": "预计下调630元/吨(0.48元/升-0.57元/升)", "prices": [] }province: 返回解析后的省份名称，可用来与请求参数做比对，确认城市名归属是否正确。update_date: 数据发布日期，代表该条用量说明是哪个交易日/用量说明周期的数据。next_adjustment: 下一次调价时间，由发改委调价周期推算得出。forecast: 下一轮调整的预测方向与幅度，单位为「元/吨」及「元/升」，仅供参考。prices: 油品用量说明数组，每项包含name、type、price、unit四个字段。
prices 数组
prices中固定包含 4 类油品：92 号汽油、95 号汽油、98 号汽油、0 号柴油。每项的结构如下：
{ "name": "92号汽油", "price": 7.96, "type": "gasoline_92", "unit": "元/升" }type是机器可读的油品标识，name是展示用的中文名称。用量说明数值以「元/升」为单位，直接可用于计算，无需再做除法或单位换算。
常见错误与排查思路
省份解析失败
若传入不存在的省份或无法识别的城市名，接口行为以实际返回为准。通常，接口会返回非 0 的code值，此时msg字段会包含具体错误描述。建议在调用前对用户输入做一次白名单校验，保证省份名在 31 个省级行政区集合内。
请求体格式错误
请求体不是合法 JSON、或province字段缺失，接口可能返回 4xx 状态码。排查时先确认 Content-Type 设置正确，并检查请求体是否被正确转义。
鉴权失败
匿名调用与携带 Key 调用的额度不同。若返回 401 或额度相关错误，检查 Header 中的 Key 是否拼写无误、是否配置了正确环境变量。
限流触发
工程化注意事项
数据缓存策略
油价并非每秒都在变化，同一省份同一天的用量说明数据理论上是稳定的。建议将响应结果按province + update_date作为缓存键，存入 Redis 或本地内存，缓存有效期可设置为 1 小时。这样可以将实际接口调用频率降低到原来的 1/3600，极大缓解 QPS 压力。
定时任务同步全量数据
若需要覆盖 31 个省份的完整数据，可使用定时任务逐省请求。由于 QPS 上限为 10，31 次请求在串行模式下约需 4 秒即可完成（每次请求 100ms+ 网络延迟）。建议每 6 小时同步一次全量数据，写入数据库并保留历史快照，便于后续分析涨价/降价趋势。
异常重试设计
网络请求天然存在不确定性。建议实现如下重试策略：
- 5xx 错误：最多重试 3 次，间隔 1s/2s/4s；
- 4xx 错误：不重试，直接记录错误日志；
- 超时：每次请求设置 5~10 秒超时，超时后按 5xx 处理；
- 返回数据中
code != 0：不重试，打印request_id和msg辅助排查。
与现有业务系统的集成
在实际项目中，建议将 API 客户端封装为独立模块，输入省份名，输出结构化油价对象。这样上层业务可以忽略接口细节，统一通过接口层访问数据，未来切换数据源时也只需修改客户端实现。
参考文档
- 全国油价 API 文档页
- 原始文档