Package: pyalex
PyAlexPyAlex is a Python library forOpenAlex. OpenAlex is
an index of hundreds of millions of interconnected scholarly papers, authors,
institutions, and more. OpenAlex offers a robust, open, and freeREST APIto 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:Get single entitiesFilter entitiesSearch entitiesGroup entitiesSearch filtersSelect fieldsSamplePaginationAutocomplete endpointN-gramsAuthenticationWe aim to cover the entire API, and we are looking for help. We are welcoming Pull Requests.Key featuresPipe operations- PyAlex can handle multiple operations in a sequence. This allows the developer to write understandable queries. For examples, seecode snippets.Plaintext abstracts- OpenAlexdoesn't include plaintext abstractsdue to legal constraints. PyAlex can convert the inverted abstracts intoplaintext abstracts on the fly.Permissive license- OpenAlex data is CC0 licensed :raised_hands:. PyAlex is published under the MIT license.InstallationPyAlex requires Python 3.8 or later.pipinstallpyalexGetting startedPyAlex offers support for allEntity Objects:Works,Authors,Sources,Institutions,Concepts,Publishers, andFunders.frompyaleximportWorks,Authors,Sources,Institutions,Concepts,Publishers,FundersThe polite poolThe polite poolhas much
faster and more consistent response times. To get into the polite pool, you
set your email:importpyalexpyalex.config.email="mail@example.com"Get single entityGet a single Work, Author, Source, Institution, Concept, Publisher or Funder from OpenAlex by the
OpenAlex ID, or by DOI or ROR.Works()["W2741809807"]# same asWorks()["https://doi.org/10.7717/peerj.4375"]The result is aWorkobject, 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, Venues, Institutions and ConceptsAuthors()["A2887243803"]Authors()["https://orcid.org/0000-0002-4297-0502"]# sameGet randomGet arandom Work, Author, Source, Institution, Concept, Publisher or Funder.Works().random()Authors().random()Sources().random()Institutions().random()Concepts().random()Publishers().random()Funders().random()Get abstractOnly for Works. Request a work from the OpenAlex database:w=Works()["W3128349626"]All attributes are available like documented underWorks, as well asabstract(only ifabstract_inverted_indexis 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.Get lists of entitiesresults=Works().get()For lists of entities, you can alsocountthe number of records found
instead of returning the results. This also works for search queries and
filters.Works().count()# 10338153For lists of entities, you can return the result as well as the metadata. By default, only the results are returned.results,meta=Concepts().get(return_meta=True)print(meta){'count':65073,'db_response_time_ms':16,'page':1,'per_page':25}Filter recordsWorks().filter(publication_year=2020,is_oa=True).get()which is identical to:Works().filter(publication_year=2020).filter(is_oa=True).get()Nested attribute filtersSome attribute filters are nested and separated with dots by OpenAlex. For
example, filter onauthorships.institutions.ror.In case of nested attribute filters, use a dict to build the query.Works().filter(authorships={"institutions":{"ror":"04pp8hn57"}}).get()Search entitiesOpenAlex reference:The search parameterWorks().search("fierce creatures").get()Search filterOpenAlex reference:The search filterAuthors().search_filter(display_name="einstein").get()Works().search_filter(title="cubist").get()Funders().search_filter(display_name="health").get()Sort entity listsOpenAlex reference:Sort entity lists.Works().sort(cited_by_count="desc").get()SelectOpenAlex reference:Select fields.Works().filter(publication_year=2020,is_oa=True).select(["id","doi"]).get()SampleOpenAlex reference:Sample entity lists.Works().sample(100,seed=535).get()Logical expressionsOpenAlex reference:Logical expressionsInequality:Sources().filter(works_count=">1000").get()Negation (NOT):Institutions().filter(country_code="!us").get()Intersection (AND):Works().filter(institutions={"country_code":["fr","gb"]}).get()# sameWorks().filter(institutions={"country_code":"fr"}).filter(institutions={"country_code":"gb"}).get()Addition (OR):Works().filter(institutions={"country_code":"fr|gb"}).get()PagingOpenAlex offers two methods for paging:basic (offset) pagingandcursor paging. Both methods are supported by PyAlex.Cursor paging (default)Use the methodpaginate()to paginate results. Each returned page is a list
of records, with a maximum ofper_page(default 25). By default,paginates argumentn_maxis set to 10000. UseNoneto retrieve all
results.frompyaleximportAuthorspager=Authors().search_filter(display_name="einstein").paginate(per_page=200)forpageinpager:print(len(page))Looking for an easy method to iterate the records of a pager?fromitertoolsimportchainfrompyaleximportAuthorsquery=Authors().search_filter(display_name="einstein")forrecordinchain(*query.paginate(per_page=200)):print(record["id"])Basic pagingSee limitations ofbasic pagingin the OpenAlex documentation.frompyaleximportAuthorspager=Authors().search_filter(display_name="einstein").paginate(method="page",per_page=200)forpageinpager:print(len(page))Get N-gramsOpenAlex reference:Get N-grams.Works()["W2023271753"].ngrams()Code snippetsA list of awesome use cases of the OpenAlex dataset.Cited publications (referenced works)frompyaleximportWorks# the work to extract the referenced works ofw=Works()["W2741809807"]Works()[w["referenced_works"]]Get works of a single authorfrompyaleximportWorksWorks().filter(author={"id":"A2887243803"}).get()Dataset publications in the global southfrompyaleximportWorks# the work to extract the referenced works ofw=Works()\.filter(institutions={"is_global_south":True})\.filter(type="dataset")\.group_by("institutions.country_code")\.get()Most cited publications in your organisationfrompyaleximportWorksWorks()\.filter(authorships={"institutions":{"ror":"04pp8hn57"}})\.sort(cited_by_count="desc")\.get()ExperimentalAuthenticationOpenAlex experiments with authenticated requests at the moment. Authenticate your requests withimportpyalexpyalex.config.api_key="<MY_KEY>"AlternativesDiophilais a nice Python wrapper for OpenAlex. It takes a slightly
different approach, especially interesting to those who don't like the pipe operations.R users can use the excellentOpenAlexRlibrary.LicenseMITContactThis 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. Theissue trackeris a good starting point. You can also email me atjonathandebruinos@gmail.com.