迷你号追踪

接口说明

用于追踪指定迷你号当前的游玩状态，需目标已进入房间，返回其所在房间与地图等状态信息。适合需要了解玩家实时对局情况的调用方使用。

调用地址

https://mini10.top/api/trace.php

请求方式

GET

鉴权说明

本接口无需密钥，可直接发起请求。

请求参数

请求方式：GET
鉴权：无需密钥，可直接调用

取值说明

• uin 为迷你号数字串，按字符串原样传入即可，例如 2046823487。
• uin 是本次调用唯一需要传入的参数，该参数必须传入，不能省略；不能留空或传入非数字内容。
• 仅当目标迷你号当前满足该接口查询条件时，才能获取到其游玩状态信息；否则不会返回有效的状态数据。

成功响应示例

{
  "code": 0,
  "data": {
    "roomId": "1877351595_e52b3553-e61e-46f0-860b-a4a3e73bf804",
    "uin": 2046823487,
    "aid": 69926577041540,
    "mapName": "测人心-救救我叭！",
    "cap": 12,
    "num": 11,
    "roomVersion": "1.59.0",
    "private": 0,
    "ip": "1.94.154.202",
    "Extra": {
      "label": 10,
      "thumbnail": "http://map37.mini1.cn/map/37/20261010/326fb1902566faf47322cf162ad153a7.png",
      "worldtype": 5
    }
  },
  "message": "OK"
}

响应字段说明

错误响应示例

所有业务错误均以 HTTP 200 返回，响应体统一为 JSON，其中 code 固定为 0，errcode 为业务错误码，msg 为文字说明。调用方应以 errcode 是否为 0 判断业务是否成功，而不是依赖状态码。

密钥校验失败类错误示例：

{
  "code": 0,
  "msg": "未提供调用密钥",
  "errcode": 11001
}

{
  "code": 0,
  "msg": "密钥已过期",
  "errcode": 11023
}

请求频率受限示例：

{
  "code": 0,
  "msg": "请求过于频繁",
  "errcode": 11005
}

接口状态类错误示例：

{
  "code": 0,
  "msg": "接口维护中",
  "errcode": 11006
}

请求方式不符合要求示例（本接口仅支持 GET）：

{
  "code": 0,
  "msg": "请求方式不允许",
  "errcode": 11018
}

本接口为免费接口、无需密钥，因此 11001～11004、11011、11023、11024、11025 等与密钥和积分相关的错误码在本接口上通常不会触发，但仍按统一规范定义，调用方可直接将 errcode 映射为提示文案。

业务错误码说明

错误码按类别可归纳为四组：密钥与鉴权类（11001～11003、11009、11011、11012、11019、11023、11025）、积分与计费类（11004、11010、11024）、频率与接口状态类（11005～11008、11013、11017、11018）、请求目标与转发类（11014～11016、11020～11022）。调用方建议对 11005 做退避重试，对 11006、11007、11013 停止重试并提示接口不可用，对其余错误码按 msg 内容直接展示给最终用户。

调用示例

终端 curl（bash）

curl "https://mini10.top/api/trace.php?uin=2046823487"

PHP

// PHP 示例
$uin = '2046823487';
$url = 'https://mini10.top/api/trace.php?uin=' . urlencode($uin);

$response = file_get_contents($url);
$data = json_decode($response, true);

if (isset($data['code']) && $data['code'] === 0) {
    echo '地图：' . $data['data']['mapName'] . PHP_EOL;
    echo '房间：' . $data['data']['roomId'] . PHP_EOL;
    echo '人数：' . $data['data']['num'] . '/' . $data['data']['cap'] . PHP_EOL;
}

注意事项

• 调用前需确保目标已进入房间：本接口返回的是目标迷你号当前所在房间的状态，若目标玩家未进入任何房间或已退出，将无法取得有效的房间信息，返回结果可能为空或提示失败。请勿在目标不处于房间内时反复重试。
• uin 参数取值须为纯数字：以迷你号数字字符串传入，不要携带空格、前缀符号或非数字字符；作为 GET 参数拼接时请做 URL 编码，避免因特殊字符导致参数被截断或解析异常。
• 该接口无需鉴权即意味着任何人均可调用：请求本身不携带任何身份凭据，因此不要把调用地址当作私密资源，也不要在本接口上附加任何敏感信息；同时请勿将其用于未经他人同意的持续定位或跟踪，仅限合理、合规用途。
• 控制轮询频率：游玩状态变化较快，但高频轮询既得不到更多有效信息，也可能触发站点限流而返回异常。建议同一目标的查询间隔保持在数秒以上，必要时对结果做短周期复用，不要以毫秒级并发方式批量请求。
• 始终使用 HTTPS 访问：请按给定的地址以 https:// 发起请求，不要在客户端改写成其他协议或自行拼接参数以外的路径，以免出现证书校验失败或请求被中间篡改。
• 返回字段随房间实时变化，勿长期缓存或作为存档依据：房间内人数、地图名称、容量、版本等信息均可能随时改变，示例仅表示结构；请以每次请求的实际返回为准，不要将历史结果当作当前状态对外展示。
• 谨慎处理返回中的网络地址类字段：结果中包含房间相关的网络地址信息，属于对外传播价值低且可能涉及他人隐私的内容，请避免在公开页面、截图或日志中直接展示，仅在必要范围内使用。
• 对失败结果做兜底判断：目标不存在、未进房间或服务暂不可用时，返回结构与成功时不同，请先判断状态字段再读取数据部分，避免因字段缺失导致程序异常。