semantic-scholar

# Semantic Scholar Paper Metadata Skill

Search and retrieve research paper metadata using the [Semantic Scholar Academic Graph API](https://api.semanticscholar.org/api-docs/).

**Base URL:** `https://api.semanticscholar.org/graph/v1`
**Auth:** No key required for basic use. For higher rate limits, get a free key at https://www.semanticscholar.org/product/api and pass it as `x-api-key` header.

---

## Choosing the Right Endpoint

| Goal | Endpoint |
|------|----------|
| Search by keywords/topic | `GET /paper/search` |
| Boolean/filtered bulk search | `GET /paper/search/bulk` |
| Match by exact/near-exact title | `GET /paper/search/match` |
| Look up a specific paper (DOI, arXiv, etc.) | `GET /paper/{paper_id}` |
| Fetch multiple papers at once | `POST /paper/batch` |
| Papers that cite a paper | `GET /paper/{paper_id}/citations` |
| Papers referenced by a paper | `GET /paper/{paper_id}/references` |
| Author's papers | `GET /author/{author_id}/papers` |

---

## Field Selection

All endpoints accept a `fields` parameter — a comma-separated list. Default response only includes `paperId` and `title`. Always request the fields you need.

**Common fields:**
```
paperId, corpusId, externalIds, title, abstract, year, venue,
publicationDate, authors, citationCount, referenceCount,
influentialCitationCount, isOpenAccess, openAccessPdf,
fieldsOfStudy, s2FieldsOfStudy, publicationTypes
```

**Nested fields** use dot notation:
```
authors.name, authors.affiliations,
citations.title, citations.year, citations.authors,
references.title, references.externalIds,
openAccessPdf.url
```

---

## Endpoint Details & curl Examples

### 1. Keyword Search — `/paper/search`

Best for: topic discovery, finding relevant papers by concept.

```bash
curl -G "https://api.semanticscholar.org/graph/v1/paper/search" \
  --data-urlencode "query=transformer attention mechanism" \
  --data-urlencode "fields=title,year,authors,citationCount,abstract" \
  --data-urlencode "limit=10"
```

**Filters** (all optional, combine freely):
```bash
--data-urlencode "year=2020-2024"               # year range
--data-urlencode "venue=NeurIPS,ICML"           # specific venues
--data-urlencode "fieldsOfStudy=Computer Science"
--data-urlencode "minCitationCount=50"
--data-urlencode "openAccessPdf="               # open access only (empty value = true)
--data-urlencode "publicationDateOrYear=2023-01-01:2023-12-31"
```

**Pagination:** Response includes `total`, `offset`, `next`. Use `offset=N` to page through results (max 1,000 total).

---

### 2. Bulk Search — `/paper/search/bulk`

Best for: large result sets, boolean queries, sorted/filtered exports.

Supports AND/OR/NOT operators and returns up to 1,000 results per call with token-based pagination (no 1,000 total cap).

```bash
curl -G "https://api.semanticscholar.org/graph/v1/paper/search/bulk" \
  --data-urlencode "query=large language models AND safety" \
  --data-urlencode "fields=title,year,citationCount,authors" \
  --data-urlencode "sort=citationCount:desc" \
  --data-urlencode "limit=100"
```

**Sort options:** `paperId`, `publicationDate`, `citationCount` (append `:asc` or `:desc`).

**Pagination:** Response includes a `token` field. Pass it as `&token=...` on the next call.

---

### 3. Title Match — `/paper/search/match`

Best for: "I have this paper title, give me its metadata."
Returns a single best match or 404. Includes a `matchScore`.

```bash
curl -G "https://api.semanticscholar.org/graph/v1/paper/search/match" \
  --data-urlencode "query=Attention Is All You Need" \
  --data-urlencode "fields=title,year,authors,citationCount,externalIds"
```

---

### 4. Paper by ID — `/paper/{paper_id}`

Best for: fetching full metadata when you already have an identifier.

**Supported ID formats** (prefix as shown):
| Format | Example |
|--------|---------|
| S2 Paper ID (bare) | `649def34f8be52c8b66281af98ae884c09aef38a` |
| Corpus ID | `CorpusId:215416146` |
| DOI | `DOI:10.18653/v1/2020.acl-main.463` |
| arXiv | `ARXIV:2005.14165` |
| PubMed | `PMID:23193287` |
| PubMed Central | `PMCID:PMC4535869` |
| ACL Anthology | `ACL:2020.acl-main.463` |
| Semantic Scholar URL | `URL:https://www.semanticscholar.org/paper/...` |

```bash
# By arXiv ID
curl "https://api.semanticscholar.org/graph/v1/paper/ARXIV:1706.03762?fields=title,abstract,year,authors,citationCount,referenceCount,isOpenAccess,openAccessPdf"

# By DOI
curl "https://api.semanticscholar.org/graph/v1/paper/DOI:10.1145/3292500.3330919?fields=title,year,venue,citationCount"
```

---

### 5. Batch Paper Lookup — `POST /paper/batch`

Best for: fetching metadata for a list of known paper IDs (up to 500).

```bash
curl -X POST "https://api.semanticscholar.org/graph/v1/paper/batch?fields=title,year,citationCount" \
  -H "Content-Type: application/json" \
  -d '{"ids": ["ARXIV:1706.03762", "ARXIV:2005.14165", "DOI:10.18653/v1/2020.acl-main.463"]}'
```

---

### 6. Citations & References

```bash
# Papers that CITE this paper (incoming)
curl "https://api.semanticscholar.org/graph/v1/paper/ARXIV:1706.03762/citations?fields=title,year,authors,citationCount&limit=20"

# Papers this paper CITES (outgoing)
curl "https://api.semanticscholar.org/graph/v1/paper/ARXIV:1706.03762/references?fields=title,year,authors&limit=20"
```

Response wraps each item in a `citingPaper` or `citedPaper` key:
```json
{ "data": [{ "citingPaper": { "title": "...", "year": 2023 } }] }
```

---

### 7. Author Lookup

```bash
# Find an author's ID by name
curl -G "https://api.semanticscholar.org/graph/v1/author/search" \
  --data-urlencode "query=Yoshua Bengio" \
  --data-urlencode "fields=name,affiliations,paperCount,citationCount,hIndex"

# Get their papers
curl "https://api.semanticscholar.org/graph/v1/author/{authorId}/papers?fields=title,year,citationCount&limit=20"
```

---

## Rate Limits & API Key

- Without a key: ~100 requests/5 min (shared pool)
- With a free API key: ~1 request/sec sustained

To use an API key:
```bash
curl -H "x-api-key: YOUR_KEY" "https://api.semanticscholar.org/graph/v1/paper/..."
```

Store the key in an env var: `export S2_API_KEY=...`
Then use: `-H "x-api-key: $S2_API_KEY"`

---

## Parsing Results

Use `jq` to extract fields from responses:

```bash
# List titles and citation counts from a search
curl -s -G "https://api.semanticscholar.org/graph/v1/paper/search" \
  --data-urlencode "query=BERT language model" \
  --data-urlencode "fields=title,year,citationCount" \
  --data-urlencode "limit=5" \
| jq '.data[] | "\(.citationCount)\t\(.year)\t\(.title)"'

# Get all author names from a paper
curl -s "https://api.semanticscholar.org/graph/v1/paper/ARXIV:1706.03762?fields=authors.name" \
| jq '[.authors[].name]'

# Extract open access PDF URL
curl -s "https://api.semanticscholar.org/graph/v1/paper/ARXIV:2005.14165?fields=openAccessPdf" \
| jq '.openAccessPdf.url'
```

---

## Workflow Tips

- **Start with `/paper/search/match`** when the user provides a full title — it's faster than a keyword search.
- **Use `/paper/{id}`** when they give you a DOI, arXiv link, or PubMed ID — extract the ID and call directly.
- **For "papers about X"** questions, use `/paper/search` with `minCitationCount` and `year` filters to surface foundational work.
- **For citation counts and h-index exploration**, combine `/author/search` → `/author/{id}/papers` sorted by `citationCount:desc`.
- **Always request only the fields you need** — smaller responses, faster calls.
- **When displaying results**, format as a table with title, year, venue, and citation count for readability.