Research Organization Registry (ROR) API 镜像文档

1. 镜像概述

Research Organization Registry (ROR) 是一个开放的、社区维护的全球研究机构标识符注册库，提供标准化的研究机构元数据及唯一标识符。本Docker镜像封装了ROR API服务，旨在简化本地部署流程，支持科研数据平台、学术系统等场景快速集成ROR组织信息查询能力，无需依赖外部公共API服务，提升数据访问稳定性与隐私性。

2. 核心功能与特性

2.1 核心功能

• 组织信息查询：支持通过ROR ID、名称、国家/地区等条件查询机构元数据（包括名称、别名、地址、关联机构等）。
• 全文搜索：提供基于机构名称、缩写的模糊搜索功能，支持分页与结果排序。
• 数据本地化：内置ROR数据集，支持定期自动更新，确保数据时效性。
• RESTful接口：遵循REST规范设计API端点，支持JSON格式响应，易于集成。

2.2 关键特性

• 轻量级部署：基于Alpine Linux构建，镜像体积小，资源占用低。
• 可配置化：支持通过环境变量自定义服务端口、数据更新频率、日志级别等。
• 缓存优化：内置查询结果缓存机制，提升高频查询响应速度。
• 兼容性：兼容ROR公共API接口规范，可无缝替换现有基于公共API的集成方案。

3. 使用场景与适用范围

3.1 适用场景

• 科研数据平台：为数据集添加标准化机构标识，支持数据溯源与机构关联分析。
• 学术论文系统：在论文作者 affiliations 字段中集成ROR ID，实现机构信息标准化。
• 科研管理系统：管理科研项目参与机构信息，支持跨系统数据互通。
• 开放获取平台：关联期刊/论文的出版机构信息，提升元数据规范性。

3.2 适用用户

• 学术机构IT团队、研究数据平台开发者、科研管理系统集成商。

4. 使用方法与配置说明

4.1 快速启动（Docker Run）

通过以下命令快速启动ROR API服务：

bash
docker run -d \
  --name ror-api \
  -p 8080:8080 \
  -e PORT=8080 \
  -e DATA_UPDATE_INTERVAL=7d \
  -e LOG_LEVEL=info \
  ror-api:latest

服务启动后，可通过 http://localhost:8080 访问API。

4.2 Docker Compose 配置示例

创建 docker-compose.yml 文件，集成到现有服务栈：

yaml
version: '3.8'
services:
  ror-api:
    image: ror-api:latest
    container_name: ror-api
    ports:
      - "8080:8080"
    environment:
      - PORT=8080                     # 服务监听端口
      - DATA_UPDATE_INTERVAL=7d       # 数据自动更新周期（支持d/h/m，如30d=30天）
      - LOG_LEVEL=info                # 日志级别（debug/info/warn/error）
      - CACHE_TTL=3600                # 查询结果缓存有效期（秒，默认3600）
      - MAX_SEARCH_RESULTS=100        # 单次搜索最大返回结果数（默认50）
    volumes:
      - ror-data:/app/data            # 持久化存储ROR数据集，避免容器重建丢失数据
    restart: unless-stopped

volumes:
  ror-data:  # 定义数据卷，持久化ROR数据

启动服务：

bash
docker-compose up -d

4.3 环境变量配置详解

5. API使用示例

5.1 查询机构详情（通过ROR ID）

请求：

http
GET /api/organizations/03yrm5c26

响应（示例）：

json
{
  "id": "[***]",
  "name": "University of California, Berkeley",
  "aliases": ["UC Berkeley", "Berkeley"],
  "country": {
    "code": "US",
    "name": "United States"
  },
  "types": ["Education"],
  "status": "active"
}

5.2 搜索机构（通过名称关键词）

请求：

http
GET /api/organizations/search?q=berkeley&page=1&per_page=10

参数说明：

• q：搜索关键词（必填）
• page：页码（默认1）
• per_page：每页结果数（默认10，最大不超过MAX_SEARCH_RESULTS）

响应（示例）：

json
{
  "total": 3,
  "page": 1,
  "per_page": 10,
  "results": [
    {"id": "[***]", "name": "University of California, Berkeley", ...},
    ...
  ]
}

5.3 获取所有国家/地区列表

请求：

http
GET /api/countries

响应（示例）：

json
[
  {"code": "US", "name": "United States"},
  {"code": "GB", "name": "United Kingdom"},
  ...
]

6. 注意事项

• 首次启动时，镜像会自动下载最新ROR数据集（约100MB），耗时取决于网络环境，建议通过 docker logs ror-api 查看进度。
• 持久化数据卷（ror-data）需妥善备份，避免数据丢失。
• 自定义 DATA_SOURCE_URL 时，确保数据源格式与***ROR数据集兼容（JSON Lines格式）。