开放平台

ArcadiaBase 开放 RESTful API，提供 Box3 与 Dao3 资源检索与推荐数据访问。所有接口基于 Cloudflare Pages Functions 部署，无需鉴权，直接通过 HTTPS GET 请求调用。

Base URL：https://arcadia-base.pages.dev
所有接口返回 Content-Type: application/json，字符编码 UTF-8。

GET/api/searchGET/api/recommend

GET/api/search

跨数据源统一检索。支持 Box3、Dao3、Box3 搜索三个数据源，返回分页结果及各数据源命中数。搜索为大小写不敏感的子串匹配。

请求参数

名称	类型	必填	默认值	说明
q	string	否	—	搜索关键词，为空时返回全部条目。匹配名称、作者、Hash、内容ID等字段
sources	string	否	box3,dao3,box3-search	数据源，逗号分隔。可选值：box3 / dao3 / box3-search
contentType	integer	否	—	内容类型筛选。1 = 地图，2 = 模型，3 = 音乐。不传则不过滤
tab	string	否	—	Dao3 分类筛选键，如 mapParkour、mapSurvival。仅对 dao3 数据源生效
page	integer	否	1	页码，从 1 开始
limit	integer	否	20	每页返回条数，范围 1 ~ 10000

响应字段

字段	类型	说明
results	array	当前页结果列表，每项包含 source 和 data 字段
results[].source	string	数据源标识："box3" \| "dao3" \| "box3-search"
results[].data	object	该条目的完整数据对象，结构因 source 不同而异（见数据模型）
total	integer	符合条件的结果总数（跨所有页）
counts	object	各数据源命中数，如 { "box3": 212, "dao3": 6729, "box3-search": 18015 }
page	integer	当前页码
limit	integer	每页条数

响应示例

JSON

{
  "results": [
    {
      "source": "box3",
      "data": {
        "n": "ParkourAdventure",
        "a": "User001",
        "h": "QmX1Y2Z3W4R5T6...",
        "ai": 12345,
        "d": "A parkour map with 10 stages"
      }
    },
    {
      "source": "dao3",
      "data": {
        "contentId": 67890,
        "name": "SurvivalIsland",
        "author": { "nickname": "BuilderX", "userId": 111 },
        "tab": { "tabKey": "mapSurvival", "tabName": "生存" },
        "playCount": 5000
      }
    }
  ],
  "total": 42,
  "counts": { "box3": 10, "dao3": 12, "box3-search": 20 },
  "page": 1,
  "limit": 20
}

请求示例

cURL

curl "https://arcadia-base.pages.dev/api/search?q=Parkour&sources=box3,dao3&contentType=1&limit=5"

URL

https://arcadia-base.pages.dev/api/search?q=Parkour&sources=box3,dao3&contentType=1&limit=5

错误响应

状态码	错误码	说明
500	database_load_failed	服务端数据库加载失败，请稍后重试

GET/api/recommend

获取 Box3 历史推荐内容。数据来源于 Box3 停运前的官方推荐列表，按内容类型分组返回。

请求参数

名称	类型	必填	默认值	说明
type	integer	否	1	内容类型：1 = 地图，2 = 模型，3 = 音乐

响应字段

字段	类型	说明
items	array	推荐内容列表
items[].contentId	integer	内容 ID
items[].name	string	内容名称
items[].authorName	string	作者昵称
items[].authorAvatar	string	作者头像 IPFS Hash
items[].type	integer	内容类型：1=地图 2=模型 3=音乐
items[].image	string	封面图 IPFS Hash
items[].hash	string	内容数据 Hash
items[].audioHash	string	音频 Hash（音乐类型）
items[].duration	integer	时长（毫秒，音乐类型）
items[].viewCount	integer	浏览数
items[].playCount	integer	游玩数（地图类型）
items[].commentCount	integer	评论数
items[].describe	string	描述
items[].createdAt	string	创建时间 ISO 字符串

响应示例

JSON

{
  "items": [
    {
      "contentId": 12345,
      "name": "StarExplorer",
      "authorName": "BuilderX",
      "authorAvatar": "QmAvatarHash...",
      "type": 1,
      "image": "QmImageHash...",
      "hash": "QmDataHash...",
      "audioHash": "",
      "duration": 0,
      "viewCount": 12000,
      "playCount": 3500,
      "commentCount": 89,
      "describe": "Explore the mysteries of the universe",
      "createdAt": "2024-01-15T10:30:00Z"
    }
  ]
}

请求示例

cURL

curl "https://arcadia-base.pages.dev/api/recommend?type=3"

URL

https://arcadia-base.pages.dev/api/recommend?type=3

错误响应

状态码	错误码	说明
500	load_failed	推荐数据加载失败，请稍后重试

数据模型

各数据源返回的 results[].data 对象结构如下，点击展开查看完整字段定义：

Dao3 分类值

使用 tab 参数筛选 Dao3 数据时，可传入以下值：

mapRolePlayingRPGmapSports竞技mapCasual休闲mapSimulator创造mapParkour跑酷mapSurvival生存mapRacing竞速mapPuzzle解密mapTycoon模拟mapOther其他

HTTP 状态码

状态码	含义
200	请求成功
400	参数错误（如 page / limit 非数字）
404	请求的端点不存在
429	速率限制触发，请降低请求频率后重试（Retry-After 头标明冷却秒数）
500	服务端内部错误

限制与配额

每页上限10,000 条

limit 参数最大值，超出自动截断

速率限制50 req/min

单 IP 每分钟最多 50 次请求，超出返回 429；建议客户端限流 30 req/min

日请求配额80,000 req/day

单 IP 每日累计上限，Cloudflare Free 计划 100K/day，预留安全余量

CPU 时限8 ms/req

Cloudflare Workers 单次调用上限 10ms，含数据库解压与检索耗时

响应体积≤ 5 MB

单次响应 JSON 体积上限，大结果集请使用分页

鉴权方式无需 API Key

公开只读接口，直接 HTTPS GET 调用

CORS已开放

Access-Control-Allow-Origin: *，支持浏览器端直接调用

运行时Cloudflare Workers

边缘计算，全球 300+ 节点低延迟响应

数据时效定期更新

非实时同步，通常每日更新一次

快速上手

JavaScript (fetch)

const resp = await fetch(
  "https://arcadia-base.pages.dev/api/search?q=Parkour&limit=5"
);
const { results, total, counts } = await resp.json();
console.log(`Total: ${total}`, counts);

Python (requests)

Python

import requests

r = requests.get("https://arcadia-base.pages.dev/api/recommend", params={"type": 3})
data = r.json()
for item in data["items"]:
    print(item["name"], item.get("duration", 0))

注意事项

IPFS Hash（Qm 开头）可通过 https://static.box3.codemao.cn/block/{hash} 获取原始数据
图片资源同理，拼接上述 CDN 前缀即可访问缩略图
Box3 CDN 服务已停运，部分 Hash 可能无法访问
请勿高频轮询，建议在应用层实现结果缓存
API 可能随数据更新发生不兼容变更，建议关注变更日志