PyAlex is a Python library for OpenAlex. OpenAlex is an index of hundreds of millions of interconnected scholarly papers, authors, institutions, and more. OpenAlex offers a robust, open, and free REST API to extract, aggregate, or search scholarly data. PyAlex is a lightweight and thin Python interface to this API. PyAlex tries to stay as close as possible to the design of the original service.
The following features of OpenAlex are currently supported by PyAlex:
We aim to cover the entire API, and we are looking for help. We are welcoming Pull Requests.
PyAlex requires Python 3.8 or later.
pip install pyalex
PyAlex offers support for all Entity Objects: Works, Authors, Sources, Institutions, Topics, Publishers, and Funders.
from pyalex import Works, Authors, Sources, Institutions, Topics, Publishers, Funders
The polite pool has much faster and more consistent response times. To get into the polite pool, you set your email:
import pyalex
pyalex.config.email = "mail@example.com"
By default, PyAlex will raise an error at the first failure when querying the OpenAlex API. You can set max_retries to a number higher than 0 to allow PyAlex to retry when an error occurs. retry_backoff_factor is related to the delay between two retry, and retry_http_codes are the HTTP error codes that should trigger a retry.
from pyalex import config
config.max_retries = 0
config.retry_backoff_factor = 0.1
config.retry_http_codes = [429, 500, 503]
Get a single Work, Author, Source, Institution, Concept, Topic, Publisher or Funder from OpenAlex by the OpenAlex ID, or by DOI or ROR.
Works()["W2741809807"]
# same as
Works()["https://doi.org/10.7717/peerj.4375"]
The result is a Work object, which is very similar to a dictionary. Find the available fields with .keys().
For example, get the open access status:
Works()["W2741809807"]["open_access"]
{'is_oa': True, 'oa_status': 'gold', 'oa_url': 'https://doi.org/10.7717/peerj.4375'}
The previous works also for Authors, Sources, Institutions, Concepts and Topics
Authors()["A2887243803"]
Authors()["https://orcid.org/0000-0002-4297-0502"] # same
Get a random Work, Author, Source, Institution, Concept, Topic, Publisher or Funder.
Works().random()
Authors().random()
Sources().random()
Institutions().random()
Concepts().random()
Topics().random()
Publishers().random()
Funders().random()
Only for Works. Request a work from the OpenAlex database:
w = Works()["W3128349626"]
All attributes are available like documented under Works, as well as abstract (only if abstract_inverted_index is not None). This abstract made human readable is create on the fly.
w["abstract"]
'Abstract To help researchers conduct a systematic review or meta-analysis as efficiently and transparently as possible, we designed a tool to accelerate the step of screening titles and abstracts. For many tasks—including but not limited to systematic reviews and meta-analyses—the scientific literature needs to be checked systematically. Scholars and practitioners currently screen thousands of studies by hand to determine which studies to include in their review or meta-analysis. This is error prone and inefficient because of extremely imbalanced data: only a fraction of the screened studies is relevant. The future of systematic reviewing will be an interaction with machine learning algorithms to deal with the enormous increase of available text. We therefore developed an open source machine learning-aided pipeline applying active learning: ASReview. We demonstrate by means of simulation studies that active learning can yield far more efficient reviewing than manual reviewing while providing high quality. Furthermore, we describe the options of the free and open source research software and present the results from user experience tests. We invite the community to contribute to open source projects such as our own that provide measurable and reproducible improvements over current practice.'
Please respect the legal constraints when using this feature.
results = Works().get()
For lists of entities, you can also count the number of records found
instead of returning the results. This also works for search queries and
filters.
Works().count()
# 10338153
For lists of entities, you can return the result as well as the metadata. By default, only the results are returned.
results, meta = Topics().get(return_meta=True)
print(meta)
{'count': 65073, 'db_response_time_ms': 16, 'page': 1, 'per_page': 25}
Works().filter(publication_year=2020, is_oa=True).get()
which is identical to:
Works().filter(publication_year=2020).filter(is_oa=True).get()
Some attribute filters are nested and separated with dots by OpenAlex. For
example, filter on authorships.institutions.ror.
In case of nested attribute filters, use a dict to build the query.
Works()
.filter(authorships={"institutions": {"ror": "04pp8hn57"}})
.get()
OpenAlex reference: The search parameter
Works().search("fierce creatures").get()
OpenAlex reference: The search filter
Authors().search_filter(display_name="einstein").get()
Works().search_filter(title="cubist").get()
Funders().search_filter(display_name="health").get()
OpenAlex reference: Sort entity lists.
Works().sort(cited_by_count="desc").get()
OpenAlex reference: Select fields.
Works().filter(publication_year=2020, is_oa=True).select(["id", "doi"]).get()
OpenAlex reference: Sample entity lists.
Works().sample(100, seed=535).get()
OpenAlex reference: Logical expressions
Inequality:
Sources().filter(works_count=">1000").get()
Negation (NOT):
Institutions().filter(country_code="!us").get()
Intersection (AND):
Works().filter(institutions={"country_code": ["fr", "gb"]}).get()
# same
Works().filter(institutions={"country_code": "fr"}).filter(institutions={"country_code": "gb"}).get()
Addition (OR):
Works().filter(institutions={"country_code": "fr|gb"}).get()
OpenAlex offers two methods for paging: basic (offset) paging and cursor paging. Both methods are supported by PyAlex.
Use the method paginate() to paginate results. Each returned page is a list
of records, with a maximum of per_page (default 25). By default,
paginates argument n_max is set to 10000. Use None to retrieve all
results.
from pyalex import Authors
pager = Authors().search_filter(display_name="einstein").paginate(per_page=200)
for page in pager:
print(len(page))
Looking for an easy method to iterate the records of a pager?
from itertools import chain
from pyalex import Authors
query = Authors().search_filter(display_name="einstein")
for record in chain(*query.paginate(per_page=200)):
print(record["id"])
See limitations of basic paging in the OpenAlex documentation.
from pyalex import Authors
pager = Authors().search_filter(display_name="einstein").paginate(method="page", per_page=200)
for page in pager:
print(len(page))
OpenAlex reference: Autocomplete entities.
Autocomplete a string:
from pyalex import autocomplete
autocomplete("stockholm resilience centre")
Autocomplete a string to get a specific type of entities:
from pyalex import Institutions
Institutions().autocomplete("stockholm resilience centre")
You can also use the filters to autocomplete:
from pyalex import Works
r = Works().filter(publication_year=2023).autocomplete("planetary boundaries")
OpenAlex reference: Get N-grams.
Works()["W2023271753"].ngrams()
All results from PyAlex can be serialized. For example, save the results to a JSON file:
with open(Path("works.json"), "w") as f:
json.dump(Works().get(), f)
with open(Path("works.json")) as f:
works = [Work(w) for w in json.load(f)]
A list of awesome use cases of the OpenAlex dataset.
from pyalex import Works
# the work to extract the referenced works of
w = Works()["W2741809807"]
Works()[w["referenced_works"]]
from pyalex import Works
Works().filter(author={"id": "A2887243803"}).get()
from pyalex import Works
# the work to extract the referenced works of
w = Works() \
.filter(institutions={"is_global_south":True}) \
.filter(type="dataset") \
.group_by("institutions.country_code") \
.get()
from pyalex import Works
Works() \
.filter(authorships={"institutions": {"ror": "04pp8hn57"}}) \
.sort(cited_by_count="desc") \
.get()
OpenAlex experiments with authenticated requests at the moment. Authenticate your requests with
import pyalex
pyalex.config.api_key = "<MY_KEY>"
R users can use the excellent OpenAlexR library.
This library is a community contribution. The authors of this Python library aren't affiliated with OpenAlex.
Feel free to reach out with questions, remarks, and suggestions. The issue tracker is a good starting point. You can also email me at jonathandebruinos@gmail.com.
FAQs
Python interface to the OpenAlex database
We found that pyalex demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.