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.
- property debug: bool#
- Type:
bool
- async get_author(author_id: str, fields: list | None = None) Author #
Author lookup
- Calls:
- Parameters:
author_id (str) – S2AuthorId.
- Returns:
author data
- Return type:
- 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:
- 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) List[Author] #
Get details for multiple authors at once
- Calls:
- Parameters:
author_ids (str) – list of S2AuthorId (must be <= 1000).
- Returns:
author data
- Return type:
List
ofsemanticscholar.Author.Author
- Raises:
BadQueryParametersException: if no author was found.
- async get_paper(paper_id: str, fields: list | None = None) Paper #
Paper lookup
- Calls:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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
ofsemanticscholar.Paper.Paper
orTuple`[:class:`List
ofsemanticscholar.Paper.Paper
,List
ofstr
]- Raises:
BadQueryParametersException: if no paper was found.
- async get_recommended_papers(paper_id: str, fields: list | None = None, limit: int = 100, pool_from: Literal['recent', 'all-cs'] = 'recent') List[Paper] #
Get recommended papers for a single positive example.
- Calls:
- 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
ofsemanticscholar.Paper.Paper
- async get_recommended_papers_from_lists(positive_paper_ids: List[str], negative_paper_ids: List[str] | None = None, fields: list | None = None, limit: int = 100) List[Paper] #
Get recommended papers for lists of positive and negative examples.
- Calls:
- 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
ofsemanticscholar.Paper.Paper
- property retry: bool#
- Type:
bool
- async search_author(query: str, fields: list | None = None, limit: int = 100) PaginatedResults #
Search for authors by name
- Calls:
- 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:
- 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) 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:
- Calls:
- 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:
- property timeout: int#
- Type:
int