从零调用全国油价API：Python实战与数据解析

原创于 2026-07-05 14:50:52 发布 · 15 阅读

0 ·

本内容遵循CC 4.0 BY-SA版权协议

GEO检测

收录于

API开发

Python实战

引言：为什么需要油价API？

在出行导航、物流调度、能源数据分析等场景中，实时油价是核心数据源之一。许多开发者希望在自己的应用或网站中嵌入油价查询功能，却苦于没有稳定、易用的数据接口。今天，我将带大家实战调用极数本源（ApiZero）平台提供的全国油价API，从注册、鉴权到数据解析，一步到位。

一、API 概览与准备

1.1 接口简介

全国油价API返回中国各省市（含港澳台）的92#、95#、98#汽油以及0#柴油的当日零售价格。数据来源权威，更新频率每日一次（上午10点前后）。接口基于RESTful风格，返回JSON格式，非常适合自动化处理。

1.2 注册与获取密钥

打开 ApiZero官网并注册账号；
登录后进入“API商城”，搜索“全国油价”；
点击“免费注册”或“立即使用”（新用户通常有免费额度）；
在“我的API”中找到 api_key（如 sk-xxxxxxxxxxxxxxxx）。

注意：密钥是敏感信息，请勿硬编码在公开代码中。推荐使用环境变量读取。

二、调用姿势：curl vs Python

2.1 直接使用 curl 测试

curl -H "Authorization: Bearer sk-你的密钥" \
  "https://api.apizero.cn/v1/oil/price?province=广东"

返回示例（已脱敏）:

{
  "code": 0,
  "msg": "success",
  "data": {
    "province": "广东",
    "update_time": "2025-03-20 10:00:00",
    "prices": {
      "92#": 7.58,
      "95#": 8.22,
      "98#": 9.35,
      "0#": 7.23
    }
  }
}

2.2 Python 完整示例（requests 库）

首先安装依赖：

pip install requests

import os
import requests
from typing import Optional, Dict

def get_oil_price(province: str, api_key: Optional[str] = None) -> Dict:
    """
    获取指定省份的油价数据
    :param province: 省份名称，如 "广东"、"北京"
    :param api_key: API密钥，默认从环境变量读取
    :return: 解析后的字典（包含 code、msg、data）
    """
    if not api_key:
        api_key = os.environ.get("OIL_API_KEY")
        if not api_key:
            raise ValueError("请设置 OIL_API_KEY 环境变量或传入 api_key 参数")

    url = "https://api.apizero.cn/v1/oil/price"
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Accept": "application/json"
    }
    params = {"province": province}

    try:
        resp = requests.get(url, headers=headers, params=params, timeout=10)
        resp.raise_for_status()  # 4xx/5xx 抛异常
        data = resp.json()
        if data.get("code") != 0:
            raise Exception(f"API 业务错误: {data.get('msg')}")
        return data
    except requests.exceptions.RequestException as e:
        raise Exception(f"网络请求失败: {e}")

# 使用示例
if __name__ == "__main__":
    result = get_oil_price("广东")
    prices = result["data"]["prices"]
    print(f"广东油价（{result['data']['update_time']}）:")
    print(f"  92#: {prices['92#']} 元/升")
    print(f"  95#: {prices['95#']} 元/升")
    print(f"  98#: {prices['98#']} 元/升")
    print(f"  0#: {prices['0#']} 元/升")

运行结果（假设环境变量已正确设置）：

广东油价（2025-03-20 10:00:00）:
  92#: 7.58 元/升
  95#: 8.22 元/升
  98#: 9.35 元/升
  0#: 7.23 元/升

三、数据处理与格式化输出

实际应用中，我们需要将原始JSON转换为更友好的格式。下面是一个简单的函数，可将油价数据输出为Markdown表格：

def prices_to_markdown(data: Dict) -> str:
    """将油价数据转为 Markdown 表格"""
    prices = data["data"]["prices"]
    lines = [
        "| 油品 | 价格（元/升） |",
        "|------|--------------|",
    ]
    for fuel, price in prices.items():
        lines.append(f"| {fuel} | {price:.2f} |")
    return "\n".join(lines)

# 使用
mk = prices_to_markdown(result)
print(mk)

输出：

| 油品 | 价格（元/升） |
|------|--------------|
| 92# | 7.58 |
| 95# | 8.22 |
| 98# | 9.35 |
| 0# | 7.23 |

四、常见问题与最佳实践

4.1 认证失败 (401)

检查密钥是否有效、是否过期；
确认请求头格式：Authorization: Bearer sk-xxx（注意 Bearer 与密钥之间的空格）；
如果使用curl，注意单引号/双引号转义。

4.2 省份名称规范

接口要求省份名称与官方行政名一致（如“内蒙古”而非“内蒙古自治区”）；
支持“全国”获取所有省份油价（返回数组）；
传入不存在的省份会返回 code=1002，msg="省份不存在"。

4.3 限流与缓存

免费用户通常每小时限100次；
建议在本地缓存数据（如Redis或内存字典），设置TTL=3600秒（1小时）；
若单机高并发，可考虑使用连接池（requests.Session）。

4.4 异步调用（aiohttp）

对于高吞吐场景，可使用异步HTTP：

import aiohttp
import asyncio

async def async_get_oil_price(province: str, api_key: str) -> Dict:
    url = f"https://api.apizero.cn/v1/oil/price?province={province}"
    headers = {"Authorization": f"Bearer {api_key}"}
    async with aiohttp.ClientSession() as session:
        async with session.get(url, headers=headers) as resp:
            data = await resp.json()
            return data

# 示例
async def main():
    key = os.environ["OIL_API_KEY"]
    result = await async_get_oil_price("北京", key)
    print(result)

asyncio.run(main())