semanticscholar 0.3.1

Unofficial Semantic Scholar Academic Graph API client library for Python.

semanticscholar

Unofficial Semantic Scholar Academic Graph API client library for Python.

How to install

pip install semanticscholar

Usage

Programmatically 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 Lookup

To access paper data:

from semanticscholar import SemanticScholar
sch = SemanticScholar()
paper = sch.get_paper('10.1093/mind/lix.236.433')
paper.title

Output:

'Computing Machinery and Intelligence'

Author Lookup

To access author data:

from semanticscholar import SemanticScholar
sch = SemanticScholar()
author = sch.get_author(2262347)
author.name

Output:

'Alan M. Turing'

Search for papers and authors

To search for papers by keyword:

from semanticscholar import SemanticScholar
sch = 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.

To search for authors by keyword:

from semanticscholar import SemanticScholar
sch = SemanticScholar()
results = sch.search_author('Alan M. Turing')
print(f'{results.total} results.', f'First occurrence: {results[0].title}.')

Output:

4 results. First occurrence: A. Turing.

Traversing search results

Each call to search_paper() and search_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 calling next_page() or simply iterating over all of them:

from semanticscholar import SemanticScholar
sch = SemanticScholar()
results = sch.search_paper('Computing Machinery and Intelligence')
for item in results:
     print(item.title)

Output:

Computing Machinery and Intelligence
Computing 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 intelligence
On Computing Machinery and Intelligence
...
Information revolution: Impact of technology on global workforce

When 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:

from semanticscholar import SemanticScholar
sch = SemanticScholar()
results = sch.search_paper('Computing Machinery and Intelligence')
for item in results.items:
     print(item.title)

Output:

Computing Machinery and Intelligence
Computing 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 intelligence
On Computing Machinery and Intelligence
...
Building Thinking Machines by Solving Animal Cognition Tasks

Query parameters for all methods

fields: list

The list of the fields to be returned. By default, the response includes all fields. As explained in official documentation, fields like papers (author lookup and search) may result in responses bigger than the usual size and affect performance. Consider reducing the list. Check official documentation for a list of available fields.

from semanticscholar import SemanticScholar
sch = SemanticScholar()
results = sch.search_paper('software engineering', fields=['title','year'])
for item in results:
     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 methods

limit: int

This 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 to official documentation, setting a smaller limit reduces output size and latency.

from semanticscholar import SemanticScholar
sch = SemanticScholar()
results = sch.search_paper('software engineering', limit=5)
len(results)

Output:

5

Query parameters for search papers

year: str

Restrict 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'.

from semanticscholar import SemanticScholar
sch = SemanticScholar()
results = sch.search_paper('software engineering', year=2000)
results[0].year

Output:

2000

fields_of_study: list

Restrict results to a given list of fields of study. Check official documentation for a list of available fields.

from semanticscholar import SemanticScholar
sch = SemanticScholar()
results = sch.search_paper('software engineering', fields_of_study=['Computer Science','Education'])
results[0].s2FieldsOfStudy

Output:

[{'category': 'Computer Science', 'source': 'external'}, {'category': 'Computer Science', 'source': 's2-fos-model'}]

Other options

timeout: int

You 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 of SemanticScholar class:

from semanticscholar import SemanticScholar
sch = SemanticScholar(timeout=5)

or set timeout property value:

from semanticscholar import SemanticScholar
sch = SemanticScholar()
sch.timeout = 5

Accessing the Data Partner's API

If you are a Semantic Scholar Data Partner you can provide the private key as an optional argument:

from semanticscholar import SemanticScholar
s2_api_key = '40-CharacterPrivateKeyProvidedToPartners'
sch = SemanticScholar(api_key=s2_api_key)

Semantic Scholar Academic Graph API docs

To get more detailed information about Semantic Scholar Academic Graph API functionalities and limitations, go to the official documentation. The Frequently Asked Questions page also provides helpful content if you need a better understanding of data fetched from Semantic Scholar services.