NodeLoc 阅读进度 API

查询 NodeLoc 用户的阅读时长、等级与升级进度的开放接口

Base URL: https://user.nodeloc.nl

简介

本服务提供两类接口，均返回 application/json 格式数据：

接口方法是否需要登录说明
/api/progress.php GET 否 查询阅读时长、等级、帖子数等公开进度指标，支持按字段筛选
/api/upgrade.php GET / POST 是（需 Cookie） 查询本人账号的升级进度，返回 14 项达标条件与等级汇总

所有成功响应都包含 ok: true，失败响应包含 ok: false 与 error 字段说明原因。

GET公开进度查询

无需登录，任何人可查任意用户的公开阅读数据。

GET /api/progress.php?username={用户名}&fields={字段列表}

请求参数

参数类型必填说明
usernamestring是NodeLoc 用户名
fieldsstring否逗号分隔的字段列表，只返回指定字段；省略 / all / * 返回全部

可用字段

字段说明
username用户名
name显示名称
avatar_template头像模板
trust_level信任等级（数字）
level_name等级名称（如「黄金会员」）
flair_name徽章标识名
badge_count徽章数
gamification_score游戏化积分
time_read累计阅读（秒）
time_read_minutes累计阅读（分钟）
recent_time_read近期阅读（秒）
posts_read_count累计阅读帖子数
topics_entered进入话题数
days_visited访问天数
likes_given送出的赞
likes_received收到的赞
post_count发帖数
topic_count主题数
solved_count已解决数
target_minutes目标阅读分钟
remaining_minutes剩余分钟（达标则为 0）
progress_percent进度百分比
goal_reached是否已达标
checked_at查询时间（ISO 8601）
cache_age_seconds结果缓存年龄（秒）

示例

# 查询全部字段
curl "https://user.nodeloc.nl/api/progress.php?username=GuDogShu"

# 只取指定字段
curl "https://user.nodeloc.nl/api/progress.php?username=GuDogShu&fields=username,trust_level,time_read_minutes,posts_read_count"

响应示例

{
  "ok": true,
  "data": {
    "username": "GuDogShu",
    "trust_level": 2,
    "level_name": "黄金会员",
    "time_read": 323000,
    "time_read_minutes": 5383,
    "posts_read_count": 21593,
    "topics_entered": 1844,
    "days_visited": 40,
    "likes_given": 39,
    "likes_received": 184,
    "gamification_score": 8260,
    "badge_count": 22,
    "target_minutes": 3000,
    "remaining_minutes": 0,
    "progress_percent": 179.43,
    "goal_reached": true,
    "checked_at": "2026-09-03T17:49:00+00:00",
    "cache_age_seconds": 120
  }
}

GET升级进度查询

查询本人账号的等级与 14 项升级达标条件。需传入登录 Cookie（仅能查 Cookie 本人）。

GET /api/upgrade.php?username={用户名}

请求参数

参数类型必填说明
usernamestring是NodeLoc 用户名（须与 Cookie 所属账号一致）
X-Nodeloc-Cookie（请求头）string是登录 Cookie，推荐放请求头（不落日志）
cookie（POST body）string是（备选）也可通过 POST body 的 cookie 字段传入
说明：Cookie 优先从请求头 X-Nodeloc-Cookie 读取，其次 POST body 的 cookie 字段。建议一律走请求头，避免 Cookie 出现在访问日志中。

示例

curl -H "X-Nodeloc-Cookie: _t=你的cookie值; _forum_session=你的会话值" \
  "https://user.nodeloc.nl/api/upgrade.php?username=GuDogShu"

响应示例（节选）

{
  "ok": true,
  "data": {
    "current_level": 2,
    "current_level_name": "黄金会员",
    "next_level": 3,
    "next_level_name": "钻石会员",
    "met_count": 8,
    "total_conditions": 14,
    "conditions": [
      {
        "key": "days_visited_100_days",
        "label": "访问天数",
        "text": "访问天数（近 100 天）：40/60",
        "value": 40,
        "target": 60,
        "met": false
      }
      // … 共 14 项
    ]
  }
}

响应字段说明

字段说明
current_level当前等级（数字）
current_level_name当前等级名称
next_level下一等级（数字）
next_level_name下一等级名称
met_count已达标条件数
total_conditions条件总数（14）
conditions条件数组，每项含 key/label/text/value/target/met
trust_level_locked等级是否锁定

错误码

HTTP 状态含义处理建议
200成功—
400参数缺失或无效（缺用户名 / 缺 Cookie）补全必填参数
401Cookie 无效或已过期重新登录 NodeLoc 并更新 Cookie
404用户不存在检查用户名拼写
429查询过于频繁（触发限流）按 retryAfterSeconds 等待后重试
502上游数据源暂时不可用稍后重试
503站点尚未安装联系管理员

限流与缓存