2b2t Atlas

2b2tAtlas 公共 API

在你自己的地图、模组或研究工具中使用 Atlas 数据。 查询地点、团体和高速公路，查找已保存的世界，或搜索已捕获的告示牌、 物品栏、生物和地图艺术作品。公开读取无需账号或 API 密钥。

此仓库包含 API 参考、HTTP 示例，以及一份 带日期的应用程序源码副本。

截至 2026 年 10 月 26 日核验：57 个公开 GET 路由和 38 个只读 MCP 工具。 记录的响应示例来自 10 月 19 日；数值和数量可能会变化。 如需准确的参数，请使用在线网站参考或 完整路由目录。

基础 URL： https://api.blackportal.cloud。 你可以通过浏览器、命令行或自己的代码发送请求。

• API 参考
• 在线 OpenAPI 架构
• 坐标与渲染图块
• BlueMap 3D 视图
• 统一查找、物品栏和已保存对象
• Nocom 数据
• MCP 设置与工具
• 集成所需的当前事实与规范链接
• 更新日志
• 源码版本与当前应用程序技术栈
• 应用程序源码快照 - 2026 年 9 月 26 日的源码和设置说明。

试用

在浏览器中打开地点列表， 或运行以下命令之一。在 Windows PowerShell 5.1 中，请使用 curl.exe。

curl --fail "https://api.blackportal.cloud/api/locations"
curl --fail "https://api.blackportal.cloud/api/groups"
curl --fail "https://api.blackportal.cloud/api/renders?limit=10"
curl --fail "https://api.blackportal.cloud/api/nocom/highways?dimension=nether&direction=northeast"

列表响应为 JSON 数组。传送点、渲染图和附件支持 limit 和 offset；默认上限为 500，最大为 1,000。地点会返回 完整目录。

对于地点选择器或目录，请使用 /api/locations/directory。它会返回 包含名称、团体、数量和首选操作的精简条目。有人打开某条记录以查看完整历史和媒体时， 再获取 /api/locations/{id}。

请求示例

examples/requests.http 包含用于目录记录、Find、物品栏和历史观测的普通 HTTP 请求。你可以通过现有的任意语言或 HTTP 工具使用 API。无需 Atlas 客户端包。

应用程序快照与当前 API 参考相互独立。 其中的设置指南介绍的是 2026 年 9 月 26 日的源码； 并未介绍之后新增的生产环境功能或运行时变更。

端点

以下所有路由均使用 GET。响应字段、筛选条件、缓存和错误信息请参阅参考文档。

资源	路由
地点	/api/locations、/api/locations/directory、/api/locations/map、/api/locations/{id}、/api/locations/aliases
团体	/api/groups、/api/groups/{id}
高速公路	/api/highways、/api/highways/{id}
存档传送点	/api/warps、/api/warps/{id}
传送点 WDL 元数据与 ZIP	/api/warps/{id}/world-download、/api/warps/{id}/world-download.zip
渲染图	/api/renders、/api/renders/{id}、/api/locations/{id}/renders
已保留的渲染源 WDL 元数据与 ZIP	/api/renders/{id}/world-download、/api/renders/{id}/world-download.zip
历史媒体	/api/attachments、/api/attachments/{id}
地图图层	/api/maprenders、/api/maprenders/catalog
统一查找	/api/find、/api/find/map、/api/find/sources、/api/find/source-options、/api/find/history、/api/find/inventory、/api/find/objects/{renderId}/{objectId}
已保存图库	/api/renders/{renderId}/explore/objects、/api/renders/{renderId}/explore/objects/{id} 及其 /art.png 预览
NoCom	/api/nocom、/api/nocom/periods、/api/nocom/highways、/api/nocom/hits 及其每日／区块／图块路由、/api/nocom/find/*
热度	/api/popularity?days=7、30 或 90

客户端行为

• 缓存目录响应，并遵循 HTTP 缓存标头。在 Minecraft 客户端中， 应在渲染／刻度线程之外执行 HTTP 请求和图像解码。
• 位置页面使用 interactiveUrl，JSON 使用 apiUrl，已保存世界使用 worldDownloadUrl。对于 Find 对象的 3D 目标位置， 优先使用 savedObject.locationLink，并基于 https://2b2tatlas.com 解析。 blueMapUrl 用于打开独立查看器，是可选项，且仅适用于渲染。
• 处理空字段，并忽略未知的 JSON 属性。
• 坐标使用记录所属的原生维度：0 为主世界，1 为下界， 2 为末地。瓦片模板中的 {y} 表示瓦片行，而不是 Minecraft 海拔。
• WDL 是不完整的历史 Java 存档。其元数据包含范围、来源、大小和 SHA-256； ZIP 下载支持 HTTP 范围请求。
• 历史坐标和渲染内容不代表服务器当前状态。 Nocom 观测次数不等于独立玩家数量。
• 已保存的物品栏来自 WDL 捕获数据。NoCom 记录容器位置， 而非容器内容。无论是旧捕获数据还是缺失的结果，都不能说明箱子后来被清空或洗劫。
• 复制记录时，请保留来源 URL、说明文字、署名和证据字段，以便核查原始材料。

MCP

端点：https://api.blackportal.cloud/mcp。传输方式：Streamable HTTP。 该服务无状态且只读，无需身份验证。

MCP 指南包含客户端配置、当前工具以及 资源 URI。注册表名称为 io.github.bobymicjohn/2b2t-atlas； 其清单文件为 server.json。

批量数据

静态导出文件托管在 2b2tatlas.com：

文件	内容
dataset.json	数据集元数据和目录链接
locations.jsonl	位置记录
groups.jsonl	群组及其关系
highways.jsonl	已批准的高速路及其关系
media.jsonl	历史媒体记录
world-downloads.jsonl	可用的不完整 WDL、校验和及来源链接
llms.txt	数据和文档索引

批量导入时请使用这些导出文件。导入记录时，请保留实体 ID 和规范 URL。 WDL 目录 也提供 HTML 视图。

现有集成

XaeroTools支持可选的 Atlas 位置叠加层，其中包含来源链接和 Atlas 地图图像的本地副本。

贡献

本地检查和拉取请求请参阅 CONTRIBUTING.md。 如需报告文档错误和不正确的请求示例，请通过 issues提交。

许可证

Atlas 编写的代码、文档和完整技术栈 均以 Unlicense 发布。你可以随意使用、修改和分享； 无需许可，也无需注明 Atlas 署名。Atlas 的事实目录同样如此。 ATTRIBUTION.md提供可选的署名格式； NOTICE.md说明第三方媒体和来源条款。

2b2tAtlas 与 Mojang Studios、Microsoft 或 2b2t 的运营者均无关联。