Using OpenAlex from Python

python
openalex
api
A note on calling the OpenAlex API from Python to retrieve paper metadata.
Published

2026-06-01

Modified

2026-06-18

Note

Original Japanese version: OpenAlexをPythonから使ってみる

Introduction

This article organizes the steps for using OpenAlex from Python to retrieve scholarly metadata such as papers and authors.

OpenAlex is a scholarly information database covering papers, authors, journals, institutions, topics, and related entities. The base URL for the API is https://api.openalex.org, and endpoints such as /works, /authors, /sources, and /institutions are available.

This article first uses the /works endpoint and shows how to search for papers by keyword and related conditions.

Preparing an API Key

An API key is required to use the OpenAlex API. Create an OpenAlex account, then obtain an API key from the settings page. Use the following link to sign up and get an API key.

Searching for Papers

From here, I explain step by step how to call the OpenAlex API from Python and search for papers.

Importing Libraries and Setting the API Key

This example uses Python’s standard os library and the external libraries requests and pandas. It assumes that the API key has been set in the environment variable OPENALEX_API_KEY, and retrieves it through os.environ. Before running the code, set OPENALEX_API_KEY=your_api_key_here in a .env file or a similar local setup in the working directory. The .env file is a text file placed at the project root to define environment variables, including the API key. When using GitHub Actions, the basic approach is not to use .env; instead, register OPENALEX_API_KEY as a repository secret and pass it from the workflow.

.env
OPENALEX_API_KEY=your_api_key_here
import os
import pandas as pd
import requests
from dotenv import load_dotenv

load_dotenv()

api_key = os.environ["OPENALEX_API_KEY"]
Important

Because .env files contain sensitive information such as API keys, make sure to add them to .gitignore and do not commit them to the Git repository.

NoteReference Links

Specifying the Endpoint and Query Parameters

To search for papers, send a GET request to the /works endpoint. For other endpoints, see the OpenAlex API documentation below.

Set the query parameters you need by referring to the “List Works” section of the API documentation. Here, I use the following parameters. - api_key: API key - search: keyword search query - filter: filtering conditions, such as publication year and document type - per_page: number of results per page - select: fields to retrieve

See the links below for the list of available parameters.

This example uses the following search conditions.

  • Keyword: “leaf economics spectrum”
  • Publication year: 2024
  • Document type: article
  • Open access: true
endpoint = "https://api.openalex.org/works"
# パラメータの設定
params = {
    "api_key": api_key,
    "search": "leaf economics spectrum",
    "filter": "publication_year:2024,type:article,open_access.is_oa:true",
    "per_page": 5,
    "select": "id,display_name,publication_year,cited_by_count,doi",
}

Creating and Sending the HTTP Request

Use requests.get() to send a GET request to the endpoint. After sending the request, call response.raise_for_status() so that an exception is raised if an HTTP error occurs.

# HTTPリクエストの作成と送信
# リクエストの送信
response = requests.get(
    endpoint,
    params=params,
    timeout=30,
)
response.raise_for_status()  # 失敗した場合は例外を発生させる

Checking the Result and Converting It to a Table

Retrieve JSON data from the response and extract the list of papers stored in the results field. Then use a list comprehension to extract the fields you need and convert them into a pandas.DataFrame for display as a table.

works = response.json()["results"]
# meta = response.json()["meta"]  # メタデータも必要に応じて取得可能

df = pd.DataFrame(
    [
        {
            "title": work["display_name"],
            "year": work["publication_year"],
            "citations": work["cited_by_count"],
            "doi": work.get("doi"),
            "openalex_id": work["id"],
        }
        for work in works
    ]
)

print(df.to_string())
Output
                                               title  year  citations                                      doi                 openalex_id
0  Life at the conservative end of the leaf econo...  2024          8     https://doi.org/10.1111/nph.20015  https://openalex.org/W4401340000
1  Extremely thin but very robust: Surprising cry...  2024          3  https://doi.org/10.1016/j.pld.2024.04.009  https://openalex.org/W4395672665
2  Plant economics spectrum governs leaf nitrogen...  2024         11  https://doi.org/10.1186/s12870-024-05484-9  https://openalex.org/W4401486401
3  Contrasting coordination of non‐structural car...  2024         45     https://doi.org/10.1111/nph.19678  https://openalex.org/W4392883019
4  Global patterns of plant functional traits and...  2024         52  https://doi.org/10.1038/s42003-024-06777-3  https://openalex.org/W4402513235

By default, results are sorted by relevance, so papers that are more relevant to the keyword are displayed first. If you want to sort by citation count, add a query parameter such as sort=cited_by_count:desc to specify the sort order.

Summary

This article introduced how to call the OpenAlex API from Python and retrieve paper metadata. It covered preparing an API key, setting the endpoint and query parameters, sending the HTTP request, processing the response, and converting the result into a table. You can apply the same approach to retrieve information about authors, journals, institutions, and other entities.

I think it is a very useful API.