Package: semanticscholar
semanticscholarUnofficial Python client library forSemantic Scholar APIs, currently supporting the Academic Graph API and Recommendations API.Table of ContentsHow to installUsagePaper LookupAuthor LookupRetrieve multiple items at onceSearch for papers and authorsTraversing search resultsRecommended papersQuery parameters for all methodsQuery parameters for all search methodsQuery parameters for search papersOther optionsAccessing the Data Partner's APISemantic Scholar API official docs and additional resourcesHow to installpip install semanticscholarUsageProgrammatically retrieve paper and author data by ID or query string.
Can be used to access both the public API and the S2 Data Partner's API using a private key.Paper LookupTo access paper data:fromsemanticscholarimportSemanticScholarsch=SemanticScholar()paper=sch.get_paper('10.1093/mind/lix.236.433')paper.titleOutput:'Computing Machinery and Intelligence'Author LookupTo access author data:fromsemanticscholarimportSemanticScholarsch=SemanticScholar()author=sch.get_author(2262347)author.nameOutput:'Alan M. Turing'Retrieve multiple items at onceYou can fetch up to 1000 distinct papers or authors in one API call. To do that, provide a list of IDs (array of strings).Get details for multiple papers:fromsemanticscholarimportSemanticScholarsch=SemanticScholar()list_of_paper_ids=['CorpusId:470667','10.2139/ssrn.2250500','0f40b1f08821e22e859c6050916cec3667778613']results=sch.get_papers(list_of_paper_ids)foriteminresults:print(item.title)Output:Improving Third-Party Audits and Regulatory Compliance in IndiaHow Much Should We Trust Differences-in-Differences Estimates?The Miracle of Microfinance? Evidence from a Randomized EvaluationGet details for multiple authors:fromsemanticscholarimportSemanticScholarsch=SemanticScholar()list_of_author_ids=['3234559','1726629','1711844']results=sch.get_authors(list_of_author_ids)foriteminresults:print(item.name)Output:E. DijkstraD. ParnasI. SommervilleSearch for papers and authorsTo search for papers by keyword:fromsemanticscholarimportSemanticScholarsch=SemanticScholar()results=sch.search_paper('Computing Machinery and Intelligence')print(f'{results.total}results.',f'First occurrence:{results[0].title}.')Output:492 results. First occurrence: Computing Machinery and Intelligence.WarningFrom theofficial documentation: "Because of the subtleties of finding partial phrase matches in different parts of the document, be cautious about interpreting the total field as a count of documents containing any particular word in the query."To search for authors by name:fromsemanticscholarimportSemanticScholarsch=SemanticScholar()results=sch.search_author('Alan M. Turing')print(f'{results.total}results.',f'First occurrence:{results[0].name}.')Output:4 results. First occurrence: A. Turing.Traversing search resultsEach call tosearch_paper()andsearch_author()will paginate through results, returning the list of papers or authors up to the bound limit (default value is 100). You can retrieve the next batch of results by callingnext_page()or simply iterating over all of them:fromsemanticscholarimportSemanticScholarsch=SemanticScholar()results=sch.search_paper('Computing Machinery and Intelligence')foriteminresults:print(item.title)Output:Computing Machinery and IntelligenceComputing Machinery and Intelligence (1950)Artificial intelligence in the research of consciousness and in social life (in honor of 70-years anniversary of A. Turing’s paper “Computing Machinery and Intelligence” (papers of the “round table”)Studies on computing machinery and intelligenceOn Computing Machinery and Intelligence...Information revolution: Impact of technology on global workforceWhen iterating over the return of search methods, the client library will always traverse all results regardless of the number of pages. If just the first batch is enough, you can avoid more calls to API, handling only current results:fromsemanticscholarimportSemanticScholarsch=SemanticScholar()results=sch.search_paper('Computing Machinery and Intelligence')foriteminresults.items:print(item.title)Output:Computing Machinery and IntelligenceComputing Machinery and Intelligence (1950)Artificial intelligence in the research of consciousness and in social life (in honor of 70-years anniversary of A. Turing’s paper “Computing Machinery and Intelligence” (papers of the “round table”)Studies on computing machinery and intelligenceOn Computing Machinery and Intelligence...Building Thinking Machines by Solving Animal Cognition TasksRecommended papersTo get recommended papers for a given paper:fromsemanticscholarimportSemanticScholarsch=SemanticScholar()results=sch.get_recommended_papers('10.2139/ssrn.2250500')foriteminresults:print(item.title)Output:Microcredit: Impacts and promising innovationsMIT Open AccessThe Econmics of Badmouthing: Libel Law and the Underworld of the Financial Press in France before World War IGive Biden a 6-PointGetting more value from Australian Intergenerational Reports...Structural Change and Economic DynamicsTo get recommended papers based on a list of positive and negative paper examples:fromsemanticscholarimportSemanticScholarsch=SemanticScholar()positive_paper_ids=['10.1145/3544585.3544600']negative_paper_ids=['10.1145/301250.301271']results=sch.get_recommended_papers_from_lists(positive_paper_ids,negative_paper_ids)foriteminresults:print(item.title)Output:BUILDING MINIMUM SPANNING TREES BY LIMITED NUMBER OF NODES OVER TRIANGULATED SET OF INITIAL NODESRecognition of chordal graphs and cographs which are Cover-Incomparability graphsMinimizing Maximum Unmet Demand by Transportations Between Adjacent Nodes Characterized by Supplies and DemandsOptimal Near-Linear Space Heaviest Induced AncestorsDiameter-2-critical graphs with at most 13 nodes...Advanced Heuristic and Approximation Algorithms (M2)You can also omit the list of negative paper IDs; in which case, the API will return recommended papers based on the list of positive paper IDs only.Query parameters for all methodsfields: listThe list of the fields to be returned. By default, the response includes all fields. As explained inofficial documentation, fields likepapers(author lookup and search) may result in responses bigger than the usual size and affect performance. Consider reducing the list. Checkofficial documentationfor a list of available fields.fromsemanticscholarimportSemanticScholarsch=SemanticScholar()results=sch.search_paper('software engineering',fields=['title','year'])foriteminresults:print(item)Output:{'paperId': 'd0bc1501ae6f54dd16534e651d90d2aeeeb1cfc1', 'title': 'Software engineering: What is it?', 'year': 2018}{'paperId': 'f70b2f20be241f445a61f33c4b8e76e554760340', 'title': 'Software Engineering for Machine Learning: A Case Study', 'year': 2019}{'paperId': '55bdaa9d27ed595e2ccf34b3a7847020cc9c946c', 'title': 'Performing systematic literature reviews in software engineering', 'year': 2006}{'paperId': '27e57cc2f22c1921d2a1c3954d5062e3fe391553', 'title': 'Guidelines for conducting and reporting case study research in software engineering', 'year': 2009}{'paperId': '81dbfc1bc890368979399874e47e0529ddceaece', 'title': "Software Engineering: A Practitioner's Approach", 'year': 1982}...Query parameters for all search methodslimit: intThis parameter represents the maximum number of results to return on each call to API, and its value can't be higher than 100, which is the default value. According toofficial documentation, setting a smaller limit reduces output size and latency.fromsemanticscholarimportSemanticScholarsch=SemanticScholar()results=sch.search_paper('software engineering',limit=5)len(results)Output:5Query parameters for search papersyear: strRestrict results to a specific publication year or a given range, following the patterns '{year}' or '{start}-{end}'. Also you can omit the start or the end. Examples: '2000', '1991-2000', '1991-', '-2000'.fromsemanticscholarimportSemanticScholarsch=SemanticScholar()results=sch.search_paper('software engineering',year=2000)results[0].yearOutput:2000fields_of_study: listRestrict results to a given list of fields of study. Checkofficial documentationfor a list of available fields.fromsemanticscholarimportSemanticScholarsch=SemanticScholar()results=sch.search_paper('software engineering',fields_of_study=['Computer Science','Education'])results[0].s2FieldsOfStudyOutput:[{'category': 'Computer Science', 'source': 'external'}, {'category': 'Computer Science', 'source': 's2-fos-model'}]Other optionstimeout: intYou can set the wait time for a response. By default, requests to API will wait for 10 seconds until the Timeout Exception raises. To change the default value, specify it at instance creation ofSemanticScholarclass:fromsemanticscholarimportSemanticScholarsch=SemanticScholar(timeout=5)or settimeoutproperty value:fromsemanticscholarimportSemanticScholarsch=SemanticScholar()sch.timeout=5Accessing the Data Partner's APIIf you are a Semantic Scholar Data Partner you can provide the private key as an optional argument:fromsemanticscholarimportSemanticScholars2_api_key='40-CharacterPrivateKeyProvidedToPartners'sch=SemanticScholar(api_key=s2_api_key)Semantic Scholar API official docs and additional resourcesIf you have concerns or feedback specific to this library, feel free toopen an issue. However, the official documentation provides additional resources for broader API-related issues.For details on Semantic Scholar APIs capabilities and limits,go to the official documentation.TheFrequently Asked Questionspage also provides helpful content if you need a better understanding of data fetched from Semantic Scholar services.Thisofficial GitHub repositoryallows users to report issues and suggest improvements.There is also a community onSlack.