AsyncSemanticScholar

class semanticscholar.AsyncSemanticScholar.AsyncSemanticScholar(timeout: int = 30, api_key: str | None = None, api_url: str | None = None, debug: bool = False, retry: bool = True)

Main class to retrieve data from Semantic Scholar Graph API asynchronously.

Parameters:

  • timeout (float) – (optional) an exception is raised if the server has not issued a response for timeout seconds.

  • api_key (str) – (optional) private API key.

  • api_url (str) – (optional) custom API url.

  • debug (bool) – (optional) enable debug mode.

  • retry (bool) – enable retry mode.

async get_author(author_id: str, fields: list | None = None) → Author

Author lookup

Calls:

GET /graph/v1/author/{author_id}

Parameters:

author_id (str) – S2AuthorId.

Returns:

author data

Return type:

semanticscholar.Author.Author

Raises:

ObjectNotFoundException: if Author ID not found.

async get_author_papers(author_id: str, fields: list | None = None, limit: int = 100) → PaginatedResults

Get details about a author’s papers

Calls:

POST /graph/v1/paper/{author_id}/papers

Parameters:

  • paper_id (str) –

    S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL, PMID, PMCID, or URL from:

    • semanticscholar.org

    • arxiv.org

    • aclweb.org

    • acm.org

    • biorxiv.org

  • fields (list) – (optional) list of the fields to be returned.

  • limit (int) – (optional) maximum number of results to return (must be <= 1000).

async get_authors(author_ids: List[str], fields: list | None = None, return_not_found: bool = False) → List[Author] | Tuple[List[Author], List[str]]

Get details for multiple authors at once

Calls:

POST /graph/v1/author/batch

Parameters:

author_ids (str) – list of S2AuthorId (must be <= 1000).

Returns:

author data, and optionally list of IDs not found.

Return type:

List of semanticscholar.Author.Author or Tuple [List of semanticscholar.Author.Author, List of str]

Raises:

BadQueryParametersException: if no author was found.

async get_autocomplete(query: str) → List[Autocomplete]

Get autocomplete suggestions for a paper query.

Calls:

GET /graph/v1/paper/autocomplete?query={query}

Parameters:

query (str) – query to get autocomplete suggestions for.

Returns:

list of autocomplete suggestions.

Return type:

List of semanticscholar.Autocomplete.Autocomplete

async get_available_releases() → List[Release]

Gets all available dataset releases.

Calls:

GET /datasets/v1/release/

Returns:

list of available release ids.

Return type:

List of str

async get_dataset_diffs(dataset_name: str, start_release_id: str, end_release_id: str) → DatasetDiff

Get incremental diffs for a dataset between two releases.

Calls:

GET /datasets/v1/diffs/{start_release_id}/to/ {end_release_id}/{dataset_name}

Parameters:

  • dataset_name (str) – Name of the dataset.

  • start_release_id (str) – ID of the release currently held by the client.

  • end_release_id (str) – ID of the release the client wishes to update to, or ‘latest’ for the most recent release.

Returns:

information containing dataset, start_release, end_release, and list of diffs.

Return type:

semanticscholar.DatasetDiff.DatasetDiff

Get download links for a specific dataset in a release.

Calls:

GET /datasets/v1/release/{release_id}/dataset/{dataset_name}

Parameters:

  • release_id (str) – Release identifier (e.g., ‘2023-12-01’).

  • dataset_name (str) – Name of the dataset.

Returns:

dataset information including download links.

Return type:

semanticscholar.Dataset.Dataset

async get_paper(paper_id: str, fields: list | None = None) → Paper

Paper lookup

Calls:

GET /graph/v1/paper/{paper_id}

Parameters:

  • paper_id (str) –

    S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL, PMID, PMCID, or URL from:

    • semanticscholar.org

    • arxiv.org

    • aclweb.org

    • acm.org

    • biorxiv.org

  • fields (list) – (optional) list of the fields to be returned.

Returns:

paper data

Return type:

semanticscholar.Paper.Paper

Raises:

ObjectNotFoundException: if Paper ID not found.

async get_paper_authors(paper_id: str, fields: list | None = None, limit: int = 100) → PaginatedResults

Get details about a paper’s authors

Calls:

POST /graph/v1/paper/{paper_id}/authors

Parameters:

  • paper_id (str) –

    S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL, PMID, PMCID, or URL from:

    • semanticscholar.org

    • arxiv.org

    • aclweb.org

    • acm.org

    • biorxiv.org

  • fields (list) – (optional) list of the fields to be returned.

  • limit (int) – (optional) maximum number of results to return (must be <= 1000).

async get_paper_citations(paper_id: str, fields: list | None = None, limit: int = 100) → PaginatedResults

Get details about a paper’s citations

Calls:

POST /graph/v1/paper/{paper_id}/citations

Parameters:

  • paper_id (str) –

    S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL, PMID, PMCID, or URL from:

    • semanticscholar.org

    • arxiv.org

    • aclweb.org

    • acm.org

    • biorxiv.org

  • fields (list) – (optional) list of the fields to be returned.

  • limit (int) – (optional) maximum number of results to return (must be <= 1000).

async get_paper_references(paper_id: str, fields: list | None = None, limit: int = 100) → PaginatedResults

Get details about a paper’s references

Calls:

POST /graph/v1/paper/{paper_id}/references

Parameters:

  • paper_id (str) –

    S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL, PMID, PMCID, or URL from:

    • semanticscholar.org

    • arxiv.org

    • aclweb.org

    • acm.org

    • biorxiv.org

  • fields (list) – (optional) list of the fields to be returned.

  • limit (int) – (optional) maximum number of results to return (must be <= 1000).

async get_papers(paper_ids: List[str], fields: list | None = None, return_not_found: bool = False) → List[Paper] | Tuple[List[Paper], List[str]]

Get details for multiple papers at once

Calls:

POST /graph/v1/paper/batch

Parameters:

  • paper_ids (str) –

    list of IDs (must be <= 500) - S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL, PMID, PMCID, or URL from:

    • semanticscholar.org

    • arxiv.org

    • aclweb.org

    • acm.org

    • biorxiv.org

  • fields (list) – (optional) list of the fields to be returned.

  • return_not_found (bool) – (optional) flag to include not found IDs in the return, except for IDs in URL:<url> format.

Returns:

papers data, and optionally list of IDs not found.

Return type:

List of semanticscholar.Paper.Paper or Tuple [List of semanticscholar.Paper.Paper, List of str]

Raises:

BadQueryParametersException: if no paper was found.

Get recommended papers for a single positive example.

Calls:

GET /recommendations/v1/papers/forpaper/{paper_id}

Parameters:

  • paper_id (str) –

    S2PaperId, CorpusId, DOI, ArXivId, MAG, ACL, PMID, PMCID, or URL from:

    • semanticscholar.org

    • arxiv.org

    • aclweb.org

    • acm.org

    • biorxiv.org

  • fields (list) – (optional) list of the fields to be returned.

  • limit (int) – (optional) maximum number of recommendations to return (must be <= 500).

  • pool_from (str) – (optional) which pool of papers to recommend from. Must be either “recent” or “all-cs”.

Returns:

list of recommendations.

Return type:

List of semanticscholar.Paper.Paper

Get recommended papers for lists of positive and negative examples.

Calls:

POST /recommendations/v1/papers/

Parameters:

  • positive_paper_ids (list) – list of paper IDs that the returned papers should be related to.

  • negative_paper_ids (list) – (optional) list of paper IDs that the returned papers should not be related to.

  • fields (list) – (optional) list of the fields to be returned.

  • limit (int) – (optional) maximum number of recommendations to return (must be <= 500).

Returns:

list of recommendations.

Return type:

List of semanticscholar.Paper.Paper

async get_release(release_id: str) → Release

Get a specific release.

Calls:

GET /datasets/v1/release/{release_id}

Parameters:

release_id (str) – Release identifier (e.g., ‘2023-12-01’).

Returns:

release information including datasets.

Return type:

semanticscholar.Release.Release

async search_author(query: str, fields: list | None = None, limit: int = 100) → PaginatedResults

Search for authors by name

Calls:

GET /graph/v1/author/search

Parameters:

  • query (str) – plain-text search query string.

  • fields (list) – (optional) list of the fields to be returned.

  • limit (int) – (optional) maximum number of results to return (must be <= 1000).

Returns:

query results.

Return type:

semanticscholar.PaginatedResults.PaginatedResults

async search_paper(query: str, year: str | None = None, publication_types: list | None = None, open_access_pdf: bool | None = None, venue: list | None = None, fields_of_study: list | None = None, fields: list | None = None, publication_date_or_year: str | None = None, min_citation_count: int | None = None, limit: int = 100, bulk: bool = False, sort: str | None = None, match_title: bool = False) → PaginatedResults | Paper

Search for papers by keyword. Performs a search query based on the S2 search relevance algorithm, or a bulk retrieval of basic paper data without search relevance (if bulk=True). Paper relevance search is the default behavior and returns up to 1,000 results. Bulk retrieval instead returns up to 10,000,000 results (1,000 in each page).

Calls:

GET /graph/v1/paper/search

Calls:

GET /graph/v1/paper/search/bulk

Parameters:

  • query (str) – plain-text search query string.

  • year (str) – (optional) restrict results to the given range of publication year.

  • publication_type (list) – (optional) restrict results to the given publication type list.

  • open_access_pdf (bool) – (optional) restrict results to papers with public PDFs.

  • venue (list) – (optional) restrict results to the given venue list.

  • fields_of_study (list) – (optional) restrict results to given field-of-study list, using the s2FieldsOfStudy paper field.

  • fields (list) – (optional) list of the fields to be returned.

  • publication_date_or_year (str) – (optional) restrict results to the given range of publication date in the format <start_date>:<end_date>, where dates are in the format YYYY-MM-DD, YYYY-MM, or YYYY.

  • min_citation_count (int) – (optional) restrict results to papers with at least the given number of citations.

  • limit (int) – (optional) maximum number of results to return (must be <= 100).

  • bulk (bool) – (optional) bulk retrieval of basic paper data without search relevance (ignores the limit parameter if True and returns up to 1,000 results in each page).

  • sort (str) – (optional) sorts results (only if bulk=True) using <field>:<order> format, where “field” is either paperId, publicationDate, or citationCount, and “order” is asc (ascending) or desc (descending).

  • match_title (bool) – (optional) retrieve a single paper whose title best matches the given query.

Returns:

query results.

Return type:

semanticscholar.PaginatedResults.PaginatedResults or semanticscholar.Paper.Paper

async search_snippet(query: str, paper_ids: List[str] | None = None, authors: List[str] | None = None, min_citation_count: int | None = None, year: str | None = None, venue: list | None = None, fields_of_study: list | None = None, fields: list | None = None, publication_date_or_year: str | None = None, limit: int = 10) → List[Snippet]

Search for text snippets matching a query. Text snippets are excerpts of approximately 500 words, drawn from a paper’s title, abstract, and body text.

Calls:

GET /graph/v1/snippet/search

Parameters:

  • query (str) – plain-text search query string.

  • paper_ids (list) – (optional) restrict results to snippets from specific papers (up to ~100 IDs).

  • authors (list) – (optional) restrict results to papers with authors matching the given names.

  • min_citation_count (int) – (optional) restrict results to papers with at least the given number of citations.

  • year (str) – (optional) restrict results to the given range of publication year.

  • venue (list) – (optional) restrict results to the given venue list.

  • fields_of_study (list) – (optional) restrict results to given field-of-study list.

  • fields (list) – (optional) list of the snippet fields to be returned.

  • publication_date_or_year (str) – (optional) restrict results to the given range of publication date in the format <start_date>:<end_date>.

  • limit (int) – (optional) maximum number of results to return (must be <= 1000, default 10).

Returns:

list of snippet search results.

Return type:

List of semanticscholar.Snippet.Snippet

property debug: bool

Enable/disable debug mode.

Type:

bool

Deprecated since version 0.8.4: Use Python’s standard logging in DEBUG level instead.

property retry: bool

Enable/disable retry mode.

Type:

bool

property timeout: int

Timeout for server response in seconds.

Type:

int