公开工具登记

GET /api/v1/entities · 1 单位

search_cultural_entities

按名称、别名、类型、城市或主题查找已发布文化实体。

限制: 用于发现本数据集中的记录;空结果不能证明现实中不存在该实体。

GET /api/v1/entities/{entity_id} · 1 单位

get_entity_evidence

获取一个实体的已审核事实、直接关系和来源定位。

限制: 不会提供公开记录中不存在的引文或关系。

POST /api/v1/visitability/check · 每个去重地点 1 单位

check_place_visitability

在带 offset 的指定时间判断一个或多个地点的排期访问条件。

限制: 结果是有证据依据的规划信息,不是实时保证。

POST /api/v1/walks/plan · 10 单位

build_cultural_walk

从已审核地点和路段构建受时间与证据约束的文化步行。

限制: 缺少的路段保持未知;距离、时长和几何绝不推测。

POST /api/v1/research-packs/build · 20 单位

build_research_pack

从已发布事实确定性生成 JSON、Markdown 或 BibTeX 资料包。

限制: 导出保留争议、未知项与权利限制;它不是自动生成的叙事。

GET /api/v1/coverage · 1 单位

get_dataset_coverage

查看当前数据发布的实际范围、缺口和新鲜度分布。

限制: 数量根据已发布数据计算,绝不替换成编辑目标数字。

发现端点

从覆盖范围开始

先检查数据集覆盖,再搜索稳定实体 ID。依赖某个关系前先查看证据;把室内地点加入步行前先核查到访条件。

REST 与 MCP

REST API 使用一致响应封套;Remote MCP 通过 Streamable HTTP 暴露同样六项能力。标记为 partial 或 unknown 的领域结果仍是有效结果,不是协议失败。

OpenAPI 描述 REST 操作,MCP 工具发现描述启用的工具登记。被禁用的工具不得继续出现在任一界面。

认证与费用单位

少量公共读取可匿名进行。API key 可以扩展已配置额度,但它不是 OAuth;不得放在 URL、浏览器存储或公开日志中。

费用单位只用于计量服务使用,并非付款。首版只做只读计算,不会在外部购买、预订、发送或发布任何内容。

稳定格式

核心实体和证据提供 HTML、Markdown 与 JSON。每种表示都保留来源、审核日期、数据版本、未知项和权利限制。