NIU Scooter API - 小牛电动车数据读取

简介

通过小牛电动车官方 MCP API 和逆向 APP API 读取车辆实时状态，包括电量、位置、里程、骑行记录等。

双模式设计

官方 API 返回字段

• batteryLevel - 电量百分比 (0-100)
• estimatedRange - 预估续航 (km)
• isCharging - 是否充电中
• chargingRemainingTime - 剩余充电时间 (分钟)
• location - 当前位置文字地址
• totalMileage - 总里程 (km)
• lastUpdate - 最后更新时间

逆向 API 返回字段

• 电池信息：电量、健康度、温度、循环次数
• 实时状态：速度、充电状态、锁车状态、GPS坐标
• 总体统计：总里程、使用天数
• 骑行记录：历史行程数据
• 双电池支持（如果有）

安装依赖

pip install requests==2.32.3 matplotlib==3.9.0

快速开始

方式一：官方 API（推荐）

1. 获取 API Key：打开小牛 APP → 「我的」→ 「API-Key Management」
2. 设置环境变量：export NIU_API_KEY=your_key
3. 运行：

python3 scripts/niu_reader_v2.py official

方式二：逆向 API

python3 scripts/niu_reader_v2.py reverse <手机号> <密码>

脚本工具

里程统计功能

计算指定日期范围内的里程

def calculate_distance_in_range(tracks, start_date_str, end_date_str):
    """计算指定日期范围内的里程，返回总里程和每日明细"""
    from datetime import datetime
    start_date = datetime.strptime(start_date_str, "%Y-%m-%d").date()
    end_date = datetime.strptime(end_date_str, "%Y-%m-%d").date()
    
    total = 0
    daily_stats = {}
    
    for track in tracks:
        track_ts = track.get("startTime", 0) / 1000
        track_date = datetime.fromtimestamp(track_ts).date()
        
        if start_date <= track_date <= end_date:
            dist = track.get("distance", 0)
            total += dist
            date_str = track_date.strftime("%Y-%m-%d")
            if date_str not in daily_stats:
                daily_stats[date_str] = {"count": 0, "distance": 0}
            daily_stats[date_str]["count"] += 1
            daily_stats[date_str]["distance"] += dist
    
    return total, daily_stats

示例输出

【4月14日至今里程】
  日期范围: 2026-04-14 ~ 2026-04-21
  累计里程: 82,405 m (82.41 km)
  骑行次数: 45 次

  每日明细:
    2026-04-14: 6.96 km (5 次)
    2026-04-15: 13.64 km (8 次)
    2026-04-16: 11.44 km (5 次)
    2026-04-17: 24.64 km (11 次)  ← 最高
    2026-04-18: 11.96 km (5 次)
    2026-04-19: 1.74 km (6 次)   ← 最少
    2026-04-20: 7.97 km (4 次)
    2026-04-21: 4.05 km (1 次)

安全说明

• 本工具仅在本地执行，不会上传用户数据到第三方服务器
• 官方 API 使用 API Key 认证，更安全
• 逆向 API 密码传输前进行 MD5 加密
• 建议使用官方 API 模式，逆向 API 仅作为补充

免责声明

本工具为开源项目，仅供学习和研究使用。使用本工具可能违反小牛官方服务条款，请自行承担使用风险。

常见问题与坑

1. 官方 MCP API vs 逆向 API 数据差异

官方 API (https://ai-mcp.niu.com/claw/scooter_info) 只返回 7 个基础字段，没有骑行记录、电池健康度、历史数据。

逆向 API (app-api.niu.com) 返回完整数据，但需要账号密码。

建议：日常快速查询用官方 API，深度分析（骑行记录、里程统计）用逆向 API。

2. /motoinfo/overallTally 返回非 JSON 数据

国内版 API 访问 /motoinfo/overallTally 端点时可能返回错误格式数据（Extra data: line 1 column 5）。这是已知问题，不影响其他接口：

try:
    result = resp.json()
except Exception as e:
    print(f"API 返回非标准数据: {e}")
    return None

3. matplotlib 中文字体乱码/警告

Linux 服务器通常没有 Arial 字体，会出现大量警告。修复方案：

import matplotlib
matplotlib.rcParams['font.family'] = ['DejaVu Sans', 'Liberation Sans', 'sans-serif']
# 不要指定 Arial

4. 国内/海外 API 版本选择

手机号注册的账号必须使用国内版 API（account.niu.com），否则会返回 "User does not exist"。建议先尝试国内版，失败后自动切换海外版。

5. SkillHub 发布注意事项

• 打包时排除 __pycache__/ 和 *.jsonl 等临时文件
• 安全扫描可能会标记 pip install 命令为供应链风险
• 官方 API 模式更容易通过安全检测

版本历史

• v2.0 (2026-04-21) - 新增官方 MCP API 支持，双模式设计
• v1.0 (2026-04-21) - 初始版本，支持逆向 APP API 数据读取和统计