ustacode/aoe2-apis

# aoe2-apis **所有公开/社区的《帝国时代 II：决定版》数据 API，尽在此处——因为从头摸索这些真的太痛苦了。** 如果你曾试图回答“这个玩家刚刚和谁对战了？用的什么文明？在什么地图上？他的积分怎么了？”这类问题，你可能会发现根本不存在官方 API，大家都在用的那个（[aoe2.net](https://aoe2.net)）已经死了，而真正能用的东西其实是游戏客户端与之通信的一个未公开的后端——而且其主机地址还在不断变动。这个 repo 就是你的地图：包含了 AoE2:DE 社区使用的每一个后端、聚合器、录像解析器和库，提供了可直接复制粘贴的请求，并真实客观地说明了每个工具能做什么和不能做什么。 ## ⚡ TL;DR — 30秒速览版 只有一个真正重要的后端。那就是 AoE2:DE 游戏客户端的在线服务。它**不需要 key、不需要 token、不需要身份验证**——只需一个普通的 HTTPS `GET` 请求。 - **Host:** `https://aoe-api.worldsedgelink.com`（传统备用地址：`https://aoe-api.reliclink.com`） - **Path:** 始终为 `/community/leaderboard/`（如果是大厅，则为 `/community/advertisement/...`） - **Required param:** `title=age2`（此后端由 Relic/World's Edge 的游戏共享；`age2` 用于选择 AoE2） 现在就试试——无需设置，无需账号： ``` # 此 backend 知晓的 61 个 civs 和约 16 个 leaderboards。已于 2026-07-10 验证。 curl 'https://aoe-api.worldsedgelink.com/community/leaderboard/getAvailableLeaderboards?title=age2' ``` 你会收到 `result.code = 0` (`"SUCCESS"`) 的 JSON 响应。这就是全部的诀窍。剩下的事情就是了解你到底需要哪个 endpoint、哪些参数以及哪一层的数据——这正是本 repo 其余部分的作用所在。 ## 🧠 两个数据层（请先阅读此部分） 对于整个生态系统，最实用的心智模型是：AoE2 数据分为**两个完全不同的层**，它们来自不同的地方，而且*都不是*实时的推送流。 | | **第 1 层 — Metadata** | **第 2 层 — 游戏内详情** | |---|---|---| | **内容** | 人物 / 文明 / 地图 / 积分 / 胜负 / 排行榜 / 开放大厅 | 建造顺序、单位生产、APM、聊天、升级时代的时间点 | | **来源** | World's Edge HTTP API（游戏后端） | 录像文件：`.aoe2record`（新）/ `.mgz`（旧） | | **方式** | 轮询 HTTP endpoint，解析 JSON | 在游戏结束后解析录像文件 | | **时效** | 有延迟的、基于轮询的，**仅限已完成的比赛** | 事后分析（录像存储的是*初始状态 + 指令流*，而不是按 tick 记录的状态） | | **推送流？** | ❌ 绝无 | ❌ 绝无 | 如果你想要排名、比赛历史和大厅信息 → **第 1 层**（[后端](docs/01-worldsedge-relic-link.md)）。如果你想知道游戏内部*实际*发生了什么 → **第 2 层**（[录像与解析器](docs/03-replays-and-ingame-data.md)）。“实时”统计（如 CaptureAge 的锦标赛叠加层）是通过将一个*不断增长*的录像文件重新回放给游戏引擎来生成的——任何地方都不存在官方的实时数据流。 ``` flowchart TD WE["🏰 World's Edge / Relic Link backend
aoe-api.worldsedgelink.com
THE source of truth (Layer 1)"] RECS["🎬 Recorded games
.aoe2record / .mgz
Layer 2 (files, not an API)"] subgraph L1["Layer 1 consumers — metadata"] NET["aoe2.net
❌ DEAD / sunset"] COMP["aoe2companion
cached Relic proxy (~1–2h lag)"] INS["aoe2insights
direct backend + replay parse"] STATS["aoestats.io
weekly Parquet dumps"] YOU1["🫵 your app"] end subgraph L2["Layer 2 consumers — in-game detail"] MGZ["aoc-mgz / aoe2rec / mgz-fast
replay parsers"] CA["CaptureAge
engine-replay 'live' stats"] YOU2["🫵 your app"] end WE --> NET WE --> COMP WE --> INS WE --> STATS WE --> YOU1 STATS -. "some rows carry
replay-enhanced data" .-> RECS RECS --> MGZ RECS --> CA RECS --> YOU2 INS -. "also parses recs" .-> RECS ``` ## 📊 目录一览 本 repo 中的每个 API / 数据源一目了然。深度解析链接在[目录](#-table-of-contents)中。 | 名称 | 层 | Base URL | 认证 | 状态 | 时效性 | 最适合 | |---|---|---|---|---|---|---| | **World's Edge / Relic Link backend** | 1 | `aoe-api.worldsedgelink.com/community/` | 无 | ✅ 在线 | 准实时（轮询） | 权威来源：排行榜、个人统计、比赛历史 | | **findAdvertisements (大厅)** | 1 | `…/community/advertisement/findAdvertisements` | 无 | ✅ 在线 | 准实时（开放大厅） | 最接近“谁即将开始游戏”的数据 | | **aoestats.io** | 1 | `aoestats.io/api/db_dumps` | 无 | ✅ 在线 | 每周（周日） | 批量分析 — 每周约 236k 场比赛，以 Parquet 格式提供 | | **aoe2companion** | 1 | `data.aoe2companion.com/api/nightbot/` | 无 | ✅ 在线 | 约 1–2 小时延迟（已缓存） | 快速的排名/比赛查询，Nightbot/Discord 机器人 | | **aoe2insights** | 1 | *(无公开 API)* | — | ✅ 在线（网站） | 按需刷新 | 人工浏览；**请基于上游后端构建，而不是这个** | | **aoe2.net** | 1 | *(曾是 `aoe2.net/api`)* | — | ❌ 已下线 | — | 仅限历史数据 — API 已停用；现有的封装库已成老古董 | | **官方排行榜 / GetGlobalStats** | 1 | `stats.ageofempires.com/api/AgeII/` | 无 | ✅ 在线 | 聚合数据 | 仅限全局汇总数据（无单场比赛 API） | | **aoc-mgz** (Python) | 2 | github.com/happyleavesaoc/aoc-mgz | n/a | ✅ 在线 | 事后分析 | 权威的录像解析器 (`.mgz`/`.aoe2record`) | | **aoe2rec** (Rust/Py) | 2 | github.com/aoe2ct/aoe2rec | n/a | ✅ 在线 | 事后分析 | 现代、快速、仅支持 DE 的录像解析 | | **CaptureAge** | 2 | captureage.com | n/a | ✅ 在线 | “实时”（引擎回放） | 真正的实时锦标赛统计（World's Edge 认可） | ## 🤔 我该用哪个？ - **“我想要排名、玩家积分或他们的最近比赛。”** → [World's Edge backend](docs/01-worldsedge-relic-link.md)。`getLeaderBoard2`、`getPersonalStat`、`getRecentMatchHistory`。无需认证。 - **“我想知道现在正在开始哪些游戏。”** → [`findAdvertisements`](docs/02-live-lobbies.md)（开放大厅流）+ 轮询最近比赛历史。没有实时观战 endpoint。 - **“我正在对数百万场比赛进行批量统计 / 文明胜率分析。”** → [aoestats.io](docs/04-aggregators-and-libraries.md) 每周的 Parquet 转储。不要为此去疯狂请求后端。 - **“我只需要为 Discord 或直播机器人做一个快速的排名/比赛查询。”** → [aoe2companion 的 Nightbot API](docs/04-aggregators-and-libraries.md)（已缓存，约 1–2 小时延迟，对后端友好）。 - **“我想要游戏中的建造顺序、APM、升级时代的时间点或聊天记录。”** → 使用 `aoc-mgz` 或 `aoe2rec` 解析[录像文件](docs/03-replays-and-ingame-data.md)。那是第 2 层。 - **“我想要像锦标赛直播那样实时的游戏内资源/单位统计。”** → [CaptureAge](docs/03-replays-and-ingame-data.md)（通过引擎回放不断增长的录像）。没有任何 API 能生成这种数据。 - **“我需要将文明 / 地图 / 排行榜 ID 映射为名称。”** → [IDs 参考表](docs/06-ids-reference.md)（并且始终通过 `getAvailableLeaderboards` 进行二次核对）。 ## 📚 目录 **文档（深度解析）：** [文档索引 →](docs/README.md) 1. [World's Edge / Relic Link 后端](docs/01-worldsedge-relic-link.md) — 核心 API：主机、endpoint、参数、认证、响应 schema。 2. [实时大厅](docs/02-live-lobbies.md) — `findAdvertisements` 以及“实时”数据的真面目。 3. [录像与游戏内数据](docs/03-replays-and-ingame-data.md) — `.aoe2record`/`.mgz` 文件、解析器以及 CaptureAge。 4. [聚合器与代码库](docs/04-aggregators-and-libraries.md) — aoestats、aoe2companion、aoe4world、LibreMatch、relic_link、ageLANServer。 5. [官方与法律](docs/05-official-and-legal.md) — 官方排行榜、`GetGlobalStats` 以及（缺失的）官方 API。 6. [IDs 参考](docs/06-ids-reference.md) — 排行榜 / 比赛类型 / 文明 / 地图 ID 映射表。 7. [构建你自己的服务](docs/07-build-your-own.md) — 构建行为良好的统计服务的系统架构。 **示例（可直接运行）：** [示例索引 →](examples/README.md) - [`examples/curl/recent-matches.sh`](examples/curl/recent-matches.sh) — 使用 `curl` + `jq` 的单行命令。 - [`examples/python/fetch_recent_matches.py`](examples/python/fetch_recent_matches.py) — Python（仅使用标准库，无额外依赖）。 - [`examples/node/fetchRecentMatches.mjs`](examples/node/fetchRecentMatches.mjs) — Node（原生 `fetch`）。 **机器可读目录：** [`apis.yaml`](apis.yaml) — · **贡献指南：** [`CONTRIBUTING.md`](CONTRIBUTING.md) ## 🚀 快速开始 无需账号、无需 key、无需 SDK。只需 HTTP。 **1. 枚举天梯和文明（绝佳的冒烟测试）：** ``` curl 'https://aoe-api.worldsedgelink.com/community/leaderboard/getAvailableLeaderboards?title=age2' ``` **2. 获取玩家最近完成的比赛。** 你需要他们的 Relic `profile_id`。如果你只有一个 Steam ID 或游戏内名称，请先使用 `getPersonalStat` 进行解析（每次请求仅使用**一种**标识符类型）： ``` # 通过精确且区分大小写的 in-game alias —— 从 profiles[] array 中读取 profile_id： curl 'https://aoe-api.worldsedgelink.com/community/leaderboard/getPersonalStat?title=age2&aliases=%5B%22Hera%22%5D' # 然后通过该 profile_id 获取最近的比赛（brackets URL-encoded 为 %5B %5D）： curl 'https://aoe-api.worldsedgelink.com/community/leaderboard/getRecentMatchHistory?title=age2&profile_ids=%5B6174996%5D' ``` **预期格式** (`getRecentMatchHistory`)： ``` { "result": { "code": 0, "message": "SUCCESS" }, "matchHistoryStats": [ { "id": 123456789, "mapname": "Kawasan.rms", "matchtype_id": 6, "description": "AUTOMATCH", "startgametime": 1752100000, "completiontime": 1752101500, // present => match finished (Unix epoch seconds) "matchhistoryreportresults": [ { "profile_id": 6174996, "resulttype": 1, // 1 = win, 0 = loss "race_id": 12, // civ id "matchhistorymember": { "oldrating": 1723, "newrating": 1735, "streak": 3 } } ] } ], "profiles": [ { "profile_id": 6174996, "alias": "Hera", "name": "/steam/76561198…", "country": "ca" } ] } ``` 从 `profiles[].name` 中恢复玩家的 SteamID64（格式为 `/steam/`）。注意：这里只会显示**已完成**的比赛——不存在所谓的“当前游戏中” endpoint。 这是该查询的请求流程： ``` sequenceDiagram autonumber participant You as Your app participant BE as World's Edge backend Note over You,BE: no auth — plain HTTPS GET You->>BE: GET /community/leaderboard/getPersonalStat?title=age2&aliases=["Hera"] BE-->>You: JSON { result.code:0, profiles:[{ profile_id }] } You->>BE: GET /community/leaderboard/getRecentMatchHistory?title=age2&profile_ids=[6174996] BE-->>You: JSON { matchHistoryStats:[…completed matches…], profiles:[…] } Note over You: cache it — never proxy user traffic straight to the backend ``` 完整的 endpoint、参数和 schema 详细信息请参阅 [docs/01-worldsedge-relic-link.md](docs/01-worldsedge-relic-link.md)。 ## 🛠️ 构建你自己的服务 想要构建统计网站、机器人或分析 pipeline？黄金法则是**统一摄取一次，从你自己的存储中对外提供**——千万不要将用户流量直接代理转发到后端。缓存所有内容，请求数保持在每秒个位数水平，在遇到 `429`/`5xx` 错误时进行指数退避，并发送真实可识别的 `User-Agent`（绝不伪装成游戏或浏览器）。[构建你自己的服务指南](docs/07-build-your-own.md) 详细介绍了整个架构：身份解析、轮询/补录循环、存储，以及如何在此基础上叠加录像解析功能。 ## 📄 许可证 [MIT](LICENSE)。本目录、文档和示例均可免费使用。它们所描述的上游 API 归各自所有者所有；本 repo 既不认可也不受 World's Edge / Microsoft 认可，仅记录公开的行为。

标签：API文档, Homebrew安装, MITM代理, Python脚本, 帝国时代2, 数据接口, 游戏, 目录, 社区资源, 逆向工具