User Guide

This guide covers the primary methods available in scholarly2 for discovering and retrieving author profiles, publications, and citation networks.

Author Search Methods

`search_author_id`

Search for an author by the ID visible in the URL of a Google Scholar author profile.

>>> author = scholarly.search_author_id('Smr99uEAAAAJ')
>>> scholarly.pprint(author)
{'affiliation': 'Professor of Vision Science, UC Berkeley',
 'email_domain': '@berkeley.edu',
 'filled': False,
 'homepage': 'http://bankslab.berkeley.edu/',
 'interests': ['vision science', 'psychology', 'human factors', 'neuroscience'],
 'name': 'Martin Banks',
 'organization': 11816294095661060495,
 'scholar_id': 'Smr99uEAAAAJ',
 'source': 'AUTHOR_PROFILE_PAGE'}

`search_org`

Search by organization name and return a list of possible disambiguate organizations and their IDs.

Note

This endpoint may require a signed-in Google Scholar Citations session.

>>> scholarly.search_org('Princeton University')
[{'Organization': 'Princeton University', 'id': '4836318610601440500'}]

`search_author_by_organization`

Search for authors belonging to a specific organization ID.

Note

This endpoint may require a signed-in Google Scholar Citations session.

>>> search_query = scholarly.search_author_by_organization(4836318610601440500)
>>> author = next(search_query)

`search_keyword`

Search by keyword and return a generator of Author objects.

Note

This endpoint may require a signed-in Google Scholar Citations session.

>>> search_query = scholarly.search_keyword('Haptics')
>>> scholarly.pprint(next(search_query))

`search_keywords`

Search by multiple keywords and return a generator of Author objects.

Note

This endpoint may require a signed-in Google Scholar Citations session.

>>> search_query = scholarly.search_keywords(['crowdsourcing', 'privacy'])
>>> scholarly.pprint(next(search_query))

`search_author_custom_url`

Search by custom URL and return a generator of Author objects. The URL should target a Google Scholar Citations author-discovery page.

Note

This endpoint may require a signed-in Google Scholar Citations session.

>>> authors = scholarly.search_author_custom_url('/citations?hl=en&view_op=search_authors&mauthors=haptics')
>>> next(authors)["name"]

Publication Search Methods

`search_pubs`

Search for articles/publications and return a generator of Publication objects.

>>> search_query = scholarly.search_pubs('Perception of physical stability')
>>> scholarly.pprint(next(search_query))

Please note that the author_id array is positionally matching with the author array. You can use the author_id to get further details about the author using the search_author_id method.

When Google Scholar includes a Show more abstract expander for a result, scholarly2 prefers that expanded abstract markup automatically.

`search_single_pub`

Search for one best-match publication result and optionally fill it in immediately.

>>> pub = scholarly.search_single_pub("Machine-learned epidemiology: real-time detection of foodborne illness at scale")
>>> pub["bib"]["title"]
'Machine-learned epidemiology: real-time detection of foodborne illness at scale'

>>> filled_pub = scholarly.search_single_pub(
...     "Machine-learned epidemiology: real-time detection of foodborne illness at scale",
...     filled=True,
... )
>>> filled_pub["bib"]["publisher"]
'Nature Publishing Group'

`search_citedby`

Search by the Google Scholar publication ID from a cited-by URL.

>>> pubs = scholarly.search_citedby(2244396665447968936)
>>> first = next(pubs)
>>> first["bib"]["title"]
'Precision medicine, AI, and the future of personalized health care'

`search_pubs_custom_url`

Run a publication query from a custom Scholar URL.

>>> pubs = scholarly.search_pubs_custom_url(
...     '/scholar?as_q=&as_epq=&as_oq=SFDI+"modulated+imaging"&as_eq=&'
...     'as_occt=any&as_sauthors=&as_publication=&as_ylo=2005&as_yhi=2020&'
...     'hl=en&as_sdt=0%2C31'
... )
>>> next(pubs)["bib"]["title"]
'Angle correction for small animal tumor imaging with spatial frequency domain imaging (SFDI)'

Object Operations

`fill`

Fill the Author and Publications container objects with additional information.

About the Publications: By default, scholarly2 returns only a lightly filled object for a publication, to avoid overloading Google Scholar. Call this method when you need complete metadata (e.g., publisher, volume, full abstract).

About the Authors: If the container object passed is an Author, the sections parameter controls which profile areas to fetch:

'basics' = name, affiliation, and interests;
'indices' = h-index, i10-index, and 5-year analogues;
'counts' = number of citations per year;
'coauthors' = co-authors;
'publications' = publications;
'public_access' = public_access;
'[]' = all of the above (this is the default)

>>> author = scholarly.search_author_id('4bahYMkAAAAJ')
>>> scholarly.pprint(scholarly.fill(author, sections=['basics', 'indices', 'coauthors']))

`citedby`

This is a method for Publication container objects. It searches Google Scholar for other articles that cite this Publication and returns a Publication generator.

>>> pub = scholarly.search_single_pub("Machine learning")
>>> citing_pubs = scholarly.citedby(pub)
>>> next(citing_pubs)["bib"]["title"]
'Artificial Intelligence in urban design: A systematic review'

`bibtex`

You can export a publication to BibTeX by using the bibtex property.

>>> query = scholarly.search_pubs("A density-based algorithm for discovering clusters...")
>>> pub = next(query)
>>> scholarly.bibtex(pub)

This outputs a standard BibTeX entry ready for inclusion in your citation manager.

Journals and Funding Mandates

`get_journal_categories`

Get a dictionary of journal categories and subcategories.

>>> categories = scholarly.get_journal_categories()
>>> print(list(categories.keys())[:3])
['Business, Economics & Management', 'Chemical & Material Sciences', 'Engineering & Computer Science']

`get_journals`

Fetch top-ranking journals for a specific category and subcategory.

>>> journals = scholarly.get_journals(category='Engineering & Computer Science', subcategory='Computer Vision & Pattern Recognition')
>>> print(journals)

`save_journals_csv`

Save a list of top-ranking journals to a file in CSV format.

>>> scholarly.save_journals_csv("journals.csv", category="English", subcategory="Computer Vision & Pattern Recognition")

`download_mandates_csv`

Download a table of funding agencies as a CSV file with URLs to the funding mandates included.

>>> scholarly.download_mandates_csv("mandates.csv")