<!-- markdown -->
## 1. 引言
Crossref REST API 是一个开放的学术元数据服务平台，为全球研究社区提供DOI（数字对象标识符）相关的元数据服务。本指南详细说明如何利用Crossref API开发论文检索工具，涵盖API基础、核心功能、最佳实践及实现细节。
### 1.1 数据来源与覆盖范围
- **数据来源**：
- Crossref成员组织（学术出版机构）提交的元数据
- 自动匹配过程（识别文献间的引用关系）
- 受信任的第三方来源（如Retraction Watch）
- **数据覆盖**：
- 学术出版物、基金、期刊等学术对象的元数据
- 不包含全文内容，仅提供文献的元数据和访问链接
- 每日更新引用统计信息，元数据通常在成员提交后20分钟内可用
> ⚠️ 注意：Crossref不从网站爬取数据或从其他聚合器获取数据，因此某些字段可能缺失。
---
## 2. 核心端点详解
### 2.1 Works端点（核心论文检索）
`https://api.crossref.org/works` 是论文检索的核心端点，支持多种查询方式：
#### 2.1.1 单个记录查询
通过DOI获取单篇论文的完整元数据：
```bash
https://api.crossref.org/works/10.1000/xyz123
```
- **HTTP HEAD请求**：快速检查DOI是否存在（无响应体，仅返回状态码）
```bash
curl --head "https://api.crossref.org/works/10.1000/xyz123"
```
#### 2.1.2 过滤查询
使用`filter`参数筛选特定条件的论文：
```bash
# 2020年发表的期刊文章
https://api.crossref.org/works?filter=type:journal-article,from-pub-date:2020-01-01,until-pub-date:2020-12-31
# 指定ISSN的期刊文章
https://api.crossref.org/works?filter=issn:2050-084X
# 开放获取（CC-BY许可证）
https://api.crossref.org/works?filter=license:CC-BY
```
#### 2.1.3 关键词搜索
使用`query`参数进行全文检索（**结果不按相关性排序**）：
```bash
# 搜索包含"artificial intelligence"的标题/摘要
https://api.crossref.org/works?query=artificial+intelligence
# 搜索特定作者
https://api.crossref.org/works?query=author:"John Smith"
```
#### 2.1.4 分页处理
通过`cursor`参数实现大数据量分页：
```bash
# 第一页（必须带cursor=*）
https://api.crossref.org/works?query=AI&cursor=*&rows=100
# 第二页（使用上页返回的next-cursor）
https://api.crossref.org/works?query=AI&cursor=ABC123&rows=100
```
- **关键规则**：
- 每页最大1000条记录（`rows`参数）
- 当返回结果数量 < `rows`时，表示已到末页
- Cursor有效期5分钟
#### 2.1.5 统计摘要
使用`facet`参数获取统计信息：
```bash
# 获取2020年各类型论文数量统计（前10）
https://api.crossref.org/works?filter=from-pub-date:2020-01-01&facet=type-name:10
# 获取所有类型的统计
https://api.crossref.org/works?facet=type-name:*
```
### 2.2 其他相关端点
| 端点 | 用途 | 示例 |
|------|------|------|
| `funders` | 基金信息查询 | `https://api.crossref.org/funders?filter=location:Switzerland` |
| `journals` | 期刊信息查询 | `https://api.crossref.org/journals/2050-084X` |
| `members` | 出版机构查询 | `https://api.crossref.org/members?query=association+library` |
| `prefixes` | DOI前缀查询 | `https://api.crossref.org/prefixes/10.1000` |
---
## 3. 请求参数详解
| 参数 | 类型 | 说明 | 示例 |
|------|------|------|------|
| `filter` | string | 字段过滤条件（逗号分隔） | `type:journal-article,from-pub-date:2020-01-01` |
| `query` | string | 全文搜索关键词 | `query=climate+change` |
| `rows` | integer | 每页返回数量（默认20，最大1000） | `rows=100` |
| `cursor` | string | 分页游标（首次用`*`） | `cursor=*` |
| `sort` | string | 排序字段（如`created`、`deposited`） | `sort=created&order=desc` |
| `facet` | string | 统计字段（格式`field:count`） | `facet=type-name:10` |
### 3.1 过滤参数详解
- **日期范围**：`from-pub-date:YYYY-MM-DD,until-pub-date:YYYY-MM-DD`
- **文献类型**：`type:journal-article`, `type:book-chapter`等
- **许可协议**：`license:CC-BY`, `license:CC-BY-NC`
- **ISSN/ISBN**：`issn:2050-084X`, `isbn:978-3-16-148410-0`
- **机构ID**：`funder:100000001`
---
## 4. 响应结构解析
### 4.1 基础结构
```json
{
"status": "ok",
"message-type": "work-list",
"message": {
"items": [
{
"DOI": "10.1000/xyz123",
"title": ["Deep Learning for Natural Language Processing"],
"author": [
{"given": "John", "family": "Smith", "affiliation": [{"name": "MIT"}]},
{"given": "Jane", "family": "Doe", "affiliation": [{"name": "Stanford"}]}
],
"published-print": {"date-parts": [[2020, 1, 15]]},
"link": [
{
"URL": "https://doi.org/10.1000/xyz123",
"content-type": "text/html",
"content-version": "vor"
}
],
"reference-count": 45,
"is-referenced-by-count": 120,
"container-title": ["Journal of AI Research"],
"issn": ["2050-084X"],
"license": [{"URL": "https://creativecommons.org/licenses/by/4.0/"}]
}
],
"total-results": 1500,
"next-cursor": "ABC123"
}
}
```
### 4.2 关键字段说明
| 字段 | 说明 |
|------|------|
| `DOI` | 文献唯一标识符 |
| `title` | 文章标题列表（通常单元素数组） |
| `author` | 作者信息数组（含姓名、机构） |
| `published-print` | 实际出版日期（date-parts格式：[[年,月,日]]） |
| `link` | 访问链接（含URL和内容类型） |
| `reference-count` | 该文献引用的参考文献数量 |
| `is-referenced-by-count` | 被其他文献引用的次数 |
| `container-title` | 期刊/会议名称 |
| `issn` | 期刊ISSN号 |
| `license` | 开放获取许可协议信息 |
> 💡 **注意**：摘要（abstract）受版权保护，通常不可用；全文内容需通过`link`字段的URL访问。
---
## 5. 最佳实践与注意事项
### 5.1 用户标识与速率控制
- **必须设置**：
- `User-Agent`头：包含工具名称和开发者联系方式
- `mailto`参数：在URL中添加`mailto=your@email.com`
```bash
curl -H "User-Agent: MyResearchTool/1.0 (https://mytool.com; mailto:dev@mytool.com)" \
"https://api.crossref.org/works?query=AI&mailto=dev@mytool.com"
```
- **速率限制**：
| 池类型 | 请求速率 | 并发限制 |
|--------|----------|----------|
| Public | 50 req/sec | 5 concurrent |
| Polite | 50 req/sec | 5 concurrent |
| Plus | 150 req/sec | 15 concurrent |
- **错误处理**：
- `429 Too Many Requests`：立即暂停并指数退避重试
- `404 Not Found`：DOI不存在或来自其他注册机构
- `500 Server Error`：重试或联系Crossref支持
### 5.2 数据缓存策略
- 元数据更新延迟约20分钟，建议缓存时间≤30分钟
- 引用统计每日更新，缓存时间可设为24小时
- 对高频查询的DOI使用本地缓存（如Redis）
### 5.3 别名DOI处理
- 当查询的DOI是别名时，API会自动重定向到主DOI
- 检查响应中的`alias`字段确认别名关系
```json
{
"message": {
"alias": ["10.1000/old-doi"],
"DOI": "10.1000/new-doi"
}
}
```
---
## 6. 示例代码（Python）
### 6.1 基础查询
```python
import requests
def query_crossref(query, rows=100):
url = "https://api.crossref.org/works"
params = {
"query": query,
"rows": rows,
"mailto": "your@email.com"
}
headers = {
"User-Agent": "MyResearchTool/1.0 (https://mytool.com; mailto:your@email.com)"
}
response = requests.get(url, params=params, headers=headers)
response.raise_for_status()
return response.json()
# 示例：搜索"machine learning"相关论文
results = query_crossref("machine learning")
for item in results["message"]["items"]:
print(f"Title: {item['title'][0]}")
print(f"DOI: {item['DOI']}")
print(f"Published: {item['published-print']['date-parts'][0]}")
print("---")
```
### 6.2 分页处理
```python
def fetch_all_results(query, max_results=1000):
all_items = []
cursor = "*"
rows = 100
while len(all_items) < max_results:
params = {
"query": query,
"cursor": cursor,
"rows": min(rows, max_results - len(all_items)),
"mailto": "your@email.com"
}
headers = {"User-Agent": "MyResearchTool/1.0"}
response = requests.get("https://api.crossref.org/works",
params=params, headers=headers)
data = response.json()
items = data["message"]["items"]
all_items.extend(items)
if not items or len(items) < rows:
break
cursor = data["message"]["next-cursor"]
return all_items
```
---
## 7. 常见问题解答
### Q1: 如何判断DOI是否属于Crossref？
- 使用DOI基金会API检查注册机构：
```bash
curl https://doi.org/ra/10.1000 # 返回注册机构名称
```
- Crossref DOI前缀示例：`10.1000`, `10.1038`, `10.1109`
### Q2: 为什么查询结果不按相关性排序？
- Crossref API默认不按相关性排序，需使用`sort`参数指定排序字段（如`sort=score`）
### Q3: 如何处理跨页数据？
- 使用`cursor=*`开始，每次请求用上页返回的`next-cursor`
- 当返回结果数 < 请求的`rows`时，表示已获取所有数据
### Q4: 如何获取引用数据？
- 通过`is-referenced-by-count`字段获取被引次数
- 引用列表需通过其他服务获取（Crossref不提供完整引用列表）
### Q5: 为什么某些字段为空？
- 数据由成员提交，部分机构可能未提供完整元数据
- 摘要、参考文献等字段受版权保护可能不可用
---
## 8. 附录：参数速查表
### 8.1 支持的过滤字段
| 字段 | 说明 |
|------|------|
| `type` | 文献类型（journal-article, book-chapter等） |
| `from-pub-date` | 出版日期下限（YYYY-MM-DD） |
| `until-pub-date` | 出版日期上限（YYYY-MM-DD） |
| `issn` | 期刊ISSN号 |
| `funder` | 基金机构ID |
| `license` | 许可协议类型 |
| `member` | 出版机构ID |
### 8.2 常见HTTP状态码
| 状态码 | 含义 | 处理建议 |
|--------|------|----------|
| 200 | 成功 | 正常处理响应 |
| 404 | 不存在 | 检查DOI是否属于Crossref |
| 429 | 请求过多 | 按指数退避重试 |
| 500 | 服务器错误 | 重试或联系支持 |
---
> 📌 **重要提示**：Crossref API是开源学术基础设施的一部分，请遵守[使用规范](https://www.crossref.org/documentation/rest-api/)，保持对服务的尊重。如有问题，请通过[Crossref社区论坛](https://community.crossref.org/)反馈。
