用途:在需要按生物体(如 human/mouse)和组织(如 lung/brain)筛选、发现相关公共单细胞研究时,可用该技能程序化调用 Broad Institute Single Cell Portal 官方 REST API;也可快速获取研究级元数据(研究名称、accession、细胞数等)用于下游整理或报告,或校验某研究是否存在并按 accession 获取详情。
主要能力:直接访问官方 /single_cell/api/v1/* 端点,无需 API 密钥;支持按 organism、tissue、disease、cell_type 等维度进行分面搜索,并可获取分面字典以构建有效过滤条件;按 accession 查询研究详情;依赖极少(仅 requests==2.31.0);对 Windows 友好,可在证书问题时选择关闭 SSL 验证。
使用方式:基础端点为 https://singlecell.broadinstitute.org/single_cell/api/v1。核心端点包括 GET /search(返回研究搜索结果元数据)、GET /search/facets(返回可用的分面键值)、GET /studies/{accession}(返回指定研究详情)。分面过滤 facets 参数格式为逗号分隔的键值对,例如 organism:human,tissue:lung;部分值可含多词(如 T cell),按原样传入。size 控制返回研究数量,建议显式设置以获得确定结果。需安装 requests==2.31.0,并可通过诸如 def scp_get(path, params=None, verify_ssl=True, timeout=30) 的辅助函数调用,使用 resp.raise_for_status() 处理 HTTP 错误。
适用场景:构建脚本或工具进行无认证的检索;在编写查询前查看索引中存在的组织/疾病/细胞类型等分面;按 accession 查看研究详情。
限制:所有网络请求必须指向官方 https://singlecell.broadinstitute.org/single_cell/api/v1/*,不得使用第三方 URL。该 API 主要返回元数据,原始数据下载通常通过门户的数据集页面完成,不在这些端点覆盖范围内。如需在 Windows 上关闭 SSL 验证(verify=False)会降低传输安全性,应尽量保持 verify=True。响应结构可能变化,建议用 dict.get 防御性处理缺失键。