Semantic Scholar API 使用指南：Python 调用、API Key 与端点（2026）

The Semantic Scholar API gives developers structured access to papers, authors, and citation relationships. Its Academic Graph, Recommendations, and Datasets services address different discovery and data-access needs.

This guide follows one product feature: find papers about scientific literature graphs, resolve selected identifiers, and compare construction methods with supporting citations. Semantic Scholar handles the discovery layer; the SciSpace API takes over reading, extraction and writing.

Evidence boundary: these are documentation-checked recipes, not an authenticated performance benchmark. No latency, success-rate, or coverage measurements are claimed.

How do you get a Semantic Scholar API key?

Use the request form linked from the official API overview. Approved keys arrive by email. Keep yours on the backend and send it in the x-api-key header.

Checked October 21, 2026, the documented introductory allowance is one request per second across endpoints. Most endpoints also permit anonymous access, with a shared 1,000-request-per-second pool and possible additional throttling. That shared figure is not an application-specific allowance.

Install Requests with python -m pip install requests, then set SEMANTIC_SCHOLAR_API_KEY in your environment. The examples below use query parameters, explicit timeouts, and raise_for_status() rather than silently accepting unsuccessful responses.

Before a commercial launch, review the API license and confirm your intended use. Authentication alone does not establish permission for every use case.

Which Semantic Scholar API endpoints should you use?

The Graph base URL is https://api.semanticscholar.org/graph/v1. Choose discovery for a topic, lookup for known identifiers, and relationship endpoints for graph exploration.

These routes are defined in the official Graph specification.

For your application, separate discovery from enrichment. Collect a shortlist first, then retrieve richer fields for papers the user selects. Store the query, filters, retrieval timestamp, and identifiers so you can explain later changes in a result set.

What query syntax and pagination work?

Relevance search takes plain text, returns at most 100 records per call, and exposes at most 1,000 ranked results. Follow its next offset. Bulk search instead returns up to 1,000 papers per call and uses continuation tokens.

Bulk supports quoted phrases, + for AND, | for OR, and - for exclusion. For example, "literature graph" | "academic graph" matches either phrase.

Treat query design as testable application logic. Keep a small set of known-relevant papers and check whether query changes still retrieve them. Do not test against an exact live ranking.

Three Python recipes for discovery and enrichment

Recipe 1: retrieve a ranked shortlist

This minimal request uses the official search pattern. It prints identifiers and titles from data; it does not include a production scheduler or retry helper.

For another page, pass the returned next value as offset. Stop when it is absent.

Test empty results, missing years, and unavailable PDF links with saved fixtures. Keep those tests separate from occasional live integration checks.

Recipe 2: resolve identifiers in batches

Run this separately after the first example's setup, through your application's request scheduler. Batch lookup accepts up to 500 identifiers; fields belongs in the query string, while ids belongs in the body.

The arXiv seed identifies The Semantic Scholar Open Data Platform. It provides a concrete starting point for the methods comparison later in this guide.

Keep unresolved identifiers visible. Ask for correction or review a title-search candidate rather than silently substituting a fuzzy match.

Recipe 3: export a matching collection

Request /paper/search/bulk with the phrase query above, then repeat with each returned token.

For a resumable importer, write each page before checkpointing its token. Deduplicate stored records by identifier and retain the original request parameters alongside the checkpoint. Keep background ingestion separate from interactive search in your job queue.

Should you use the semanticscholar Python package?

The semanticscholar Python package is an unofficial client with typed responses and pagination helpers. It supports authenticated initialization through SemanticScholar(api_key=...) and paper lookup through get_paper.

Use it when its object model suits your application. Prefer direct Requests calls when you want explicit HTTP handling. Review the wrapper's retry behavior before adding another retry layer around it.

Use the Semantic Scholar API official documentation to confirm service contracts, rather than treating wrapper behavior as the service specification.

How should you handle 429 and 500 errors?

Semantic Scholar documents 429 as rate limiting and 500 as a server-side error. A 500 alone does not establish that your client exceeded an allowance.

Recommended application policy:

• 400: inspect parameters before retrying.
• 401 or 403: check credentials and permissions.
• 404: preserve the unresolved identifier for review.
• 429: slow the shared scheduler and use bounded backoff.
• 500: preserve the job and retry within a bounded policy.

These actions follow the documented error meanings, but the recovery policy is yours to implement.

Measure endpoint, status, attempt count, and elapsed time for each HTTP attempt. Report successful calls separately from retries, and record the test window and worker count. Do not turn eventual job success into a claim that every underlying request succeeded.

Where does a metadata integration stop?

Semantic Scholar includes text-snippet search, so describing it as having no textual retrieval would be inaccurate. A retrieved snippet or citation relationship, however, is not a generated comparison answering your user's question.

An openAccessPdf field supplies a link when available, not an extracted methods table.

For the literature-graph feature, your remaining application work includes fetching PDFs, parsing text, extracting datasets and methods, summarizing findings, checking support, and formatting citations. Expanding discovery adds separate source clients, provider-specific rate-limit handling, deduplication, and ranking.

That is the useful boundary: paper discovery versus an evidence-backed research workflow.

From paper discovery to finished research: the SciSpace API

Semantic Scholar finds papers and maps how they cite each other. Turning a shortlist into a comparison still means fetching PDFs, extracting methods and datasets, writing the summary and formatting citations, as the section above lists.

The SciSpace API puts the full SciSpace Agent behind one call. It searches, reads, analyses and writes, and delivers the result as ready-to-use files. It comes as two APIs:

What this adds on top of Semantic Scholar

• One integration instead of four. Instead of stitching together a search API, a PDF parser, a trials database and an LLM, describe the task in plain language and the agent picks the tools.
• Citation chasing from seed papers. The Task API follows citations forwards and backwards from papers you choose, runs up to 5 search-and-reflect rounds, then writes the review.
• Extraction tables from full text. Ask for columns such as dataset, method and limitation, and the Task API fills them from the papers' full text where available. You can then filter, sort and combine the results.
• Finished files. One run can return a LaTeX report compiled to PDF with its BibTeX, a Word document or a PowerPoint deck. You get links to every file it created.
• Your library as a source. Bring in papers from Zotero or Mendeley, or import CSV, Excel, RIS or BibTeX, and search them alongside everything else.
• Progress you can show users. The Task API streams each plan step and the answer as it's written. When it finishes, send follow-ups in the same thread to refine, extend or reformat the work.
• Questions over your own PDFs. Upload up to 10 PDFs at once and get answers with page-level citations, including content read from figures and tables.

When to use which

• Keep Semantic Scholar for graph exploration, citation counts, author data and bulk datasets.
• Use the SciSpace API when the output your users need is a literature review, an extraction table or a cited report. You can pass the DOIs and arXiv IDs you already have into the task as seed papers.

What it doesn't do

• It doesn't query Semantic Scholar. Its sources are SciSpace's 280M+ paper index, Google Scholar, PubMed and arXiv, plus your own library.
• No paywalled papers. SciSpace reads your own PDFs plus 50M+ open-access full texts.

The SciSpace API is in early access; it isn't open yet. At launch it's open to anyone: register on SciSpace and start, with no sales call. Every account gets $5 in free API credits, enough to try both APIs on real questions. The API is separate from SciSpace consumer plans; no consumer plan includes API usage.

Frequently asked questions

Last checked

Third-party documentation checked October 21, 2026. Examples were not executed as a live API benchmark.

Sources

1. Semantic Scholar API overview and key-request entry point
2. Semantic Scholar Academic Graph API documentation
3. Semantic Scholar API and Dataset License Agreement
4. semanticscholar Python client documentation

注意转载授权 · 阅读原文