SemanticScholar#

class semanticscholar.SemanticScholar.SemanticScholar(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 synchronously.

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.

property debug: bool#
Type:

bool

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

Author lookup

Calls:

GET /author/{author_id}

Parameters:

author_id (str) – S2AuthorId.

Returns:

author data

Return type:

semanticscholar.Author.Author

Raises:

ObjectNotFoundException: if Author ID not found.

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

Get details about a author’s papers

Calls:

POST /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).

get_authors(author_ids: List[str], fields: list | None = None) → List[Author]#

Get details for multiple authors at once

Calls:

POST /author/batch

Parameters:

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

Returns:

author data

Return type:

List of semanticscholar.Author.Author

Raises:

BadQueryParametersException: if no author was found.

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

Paper lookup

Calls:

GET /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.

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

Get details about a paper’s authors

Calls:

POST /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).

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

Get details about a paper’s citations

Calls:

POST /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).

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

Get details about a paper’s references

Calls:

POST /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).

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 /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`[:class:`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

property retry: bool#
Type:

bool

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

Search for authors by name

Calls:

GET /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

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) → PaginatedResults#

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 /paper/search

Calls:

GET /paper/search

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).

Returns:

query results.

Return type:

semanticscholar.PaginatedResults.PaginatedResults

property timeout: int#
Type:

int