全国油价接口能力边界解析：省份映射、返回结构与限流设计

接口定位：能做什么，不能做什么

全国油价 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 字段，有几个值得注意的细节：

• 支持「广东」「广东省」两种写法；
• 支持直辖市名称如「北京」「上海市」；
• 支持常见城市名自动归属，例如「广州」会被解析为广东；
• 内蒙古等自治区同时支持简称与全称；
• 若传入无法识别的名称，接口会返回错误码而不是猜测性匹配。

这种灵活的入参设计降低了调用方的参数标准化维护复杂度，但依赖调用方对输入值做基本的合法性校验，因为城市名到省份的归属规则并不对外公开。

鉴权方式

接口支持匿名调用，也支持通过 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 四个字段：

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 文档页
• 原始文档