# CORE API

CORE 聚合了来自全球 15,000 多个知识库的开放获取研究成果。它提供超过 3700 万篇论文的**全文**以及超过 3.68 亿篇论文的元数据。

## Base URL

```
https://api.core.ac.uk/v3
```

**重要提示：** GET 搜索路径需要**末尾斜杠**（例如 `/v3/search/works/`，而不是 `/v3/search/works`）。

## Authentication

- **请求头：** `Authorization: Bearer YOUR_API_KEY`
- **查询参数：** `?api_key=YOUR_API_KEY`
- 注册地址：https://core.ac.uk/services/api

**未认证状态：** 基本元数据查询可用，但全文**不可用**（返回 "Not available for public API users"）。

## Rate Limits（基于令牌）

| 用户类型 | 每日令牌数 | 每分钟上限 |
|-----------|-------------|----------------|
| 未认证 | 100/天 | 10/分钟 |
| 已注册个人 | 1,000/天 | 25/分钟 |
| 已注册学术用户 | 5,000/天 | 10/分钟 |

简单查询消耗 1 个令牌。下载和滚动分页消耗 3-5 个令牌。

## Key Endpoints

### 1. 搜索论文

```
GET /v3/search/works/?q={query}&limit={n}&offset={n}
```

| 参数 | 默认值 | 描述 |
|-----------|---------|-------------|
| `q` | 必填 | 搜索查询（支持字段查找、布尔运算符） |
| `limit` | 10 | 每页结果数（最大 100） |
| `offset` | 0 | 分页偏移量 |
| `scroll` | false | 启用滚动分页以获取超过 10,000 条结果 |
| `sort` | relevance | `relevance`（相关度）或 `recency`（最新） |

**POST 方式**（适用于复杂查询）：
```
POST /v3/search/works
Content-Type: application/json

{"q": "machine learning", "limit": 10, "offset": 0}
```

**示例：**
```
https://api.core.ac.uk/v3/search/works/?q=CRISPR+gene+therapy&limit=10
```

### 2. 查询语法

| 运算符 | 示例 | 描述 |
|----------|---------|-------------|
| AND | `title:"AI" AND authors:"Smith"` | 两个条件都满足 |
| OR | `title:"AI" OR fullText:"Deep Learning"` | 满足任一条件 |
| 分组 | `(title:"AI" OR title:"ML") AND yearPublished>"2020"` | 优先级 |
| 字段查找 | `title:"Machine Learning"` | 搜索指定字段 |
| 范围 | `yearPublished>2018` | 数值比较 |
| 存在性 | `_exists_:fullText` | 字段必须存在 |
| 短语 | `title:"Attention is all you need"` | 精确短语匹配 |

**可搜索字段：** `abstract`、`arxivId`、`authors`、`contributors`、`createdDate`、`dataProviders`、`depositedDate`、`documentType`、`doi`、`fullText`、`id`、`language`、`license`、`oai`、`title`、`yearPublished`

### 3. 按 ID 获取论文

```
GET /v3/works/{id}
```

`id` 是 CORE 论文 ID（整数）。示例：`/v3/works/267312`

### 4. 按 ID 获取输出

```
GET /v3/outputs/{id}
```

### 5. 下载全文

```
GET /v3/outputs/{id}/download
```

返回二进制 PDF。需要认证。

```
GET /v3/works/tei/{id}
```

返回 TEI XML 格式。

### 6. 搜索输出

```
GET /v3/search/outputs/?q={query}&limit={n}&offset={n}
```

按 DOI 搜索：`q=doi:10.1038/nature12373`

## Response Format

### 搜索结果
```json
{
  "totalHits": 2281337,
  "limit": 10,
  "offset": 0,
  "scrollId": null,
  "results": [...]
}
```

### 论文对象（关键字段）
```json
{
  "id": 8848131,
  "title": "Attention Is All You Need",
  "authors": [{"name": "Ashish Vaswani"}, ...],
  "abstract": "The dominant sequence...",
  "doi": "10.48550/arXiv.1706.03762",
  "arxivId": "1706.03762",
  "yearPublished": 2017,
  "downloadUrl": "https://core.ac.uk/download/...",
  "fullText": "Full text content (when authenticated)...",
  "language": {"code": "en", "name": "English"},
  "documentType": "research",
  "citationCount": 145678,
  "dataProviders": [{"name": "arXiv"}],
  "links": [{"type": "download", "url": "..."}]
}
```

## Pagination

- **标准分页：** `offset` + `limit`（最多 10,000 条结果）
- **滚动分页：** 设置 `scroll=true`。响应中包含 `scrollId`。在后续请求中使用以翻页超过 10,000 条结果（消耗更多令牌）。

## Error Handling

在高负载下，API 可能会返回部分分片失败消息。这些是瞬态错误——稍等片刻后重试即可。