Skip to contents

Query the OpenAlex API

Source: R/openalex.R
openalex_api_key.Rd

  • openalex_api_key() finds the key, if there is one;

  • openalex_request() prepares a request (not sent);

  • openalex_search() fetches all the pages of a query by cursor;

  • openalex_rate_limit() reads the remaining daily budget from a response.

Usage

openalex_api_key()

openalex_request(entity, query = list(), api_key = openalex_api_key())

openalex_search(
  entity,
  filter = NULL,
  search = NULL,
  select = NULL,
  query = list(),
  per_page = 200L,
  api_key = openalex_api_key(),
  pause = 0.2,
  max_pages = Inf,
  on_page = NULL
)

openalex_rate_limit(resp)

Arguments

entity

Character. "works", "authors", "sources", ...

query

Named list of query parameters.

api_key

Character. By default openalex_api_key(); "" for keyless requests.

filter, search, select

Character or NULL. The parameters of the same names of the API.

per_page

Integer. Results per page (at most 200).

pause

Numeric. Minimum seconds between two requests.

max_pages

Numeric. Maximum number of pages.

on_page

Function called with each list of results and its page number, or NULL. See api_paginate().

resp

An httr2_response from OpenAlex.

Value

openalex_api_key(): a string, empty without a key. openalex_request(): an httr2_request. openalex_search(): the list returned by api_paginate(). openalex_rate_limit(): a list with limit, remaining, credits_used and reset_in (seconds).

Details

OpenAlex works with a daily budget. Without a key it allows 10 requests per second, with a free key 30 and a budget ten times larger. A key is the environment variable OPENALEX_API_KEY (in ~/.Renviron). The former mailto "polite pool" no longer appears in the documentation consulted on 2026-11-09.

Paging past the first page needs a key (HTTP 401 otherwise, observed on 2026-11-09). Without one, openalex_search() keeps the first page, warns, and returns status = "incomplete".

A 429 can mean too many requests in a second, which is worth retrying, or a daily budget spent, which is not: openalex_search() then stops with an error of class politecollect_openalex_budget, saying when it resets. The key is sent as a header, so it does not appear in URLs or logs.

For an entire entity, the monthly snapshot is the right source: list its files and give them to queue_downloads().

References

OpenAlex, Rate limits and authentication. https://help.openalex.org/how-to-use-the-api/rate-limits-and-authentication

See also

Other APIs: api_paginate(), api_request(), crossref_request(), ia_search(), scopus_api_key(), sparql_query()

Examples

if (FALSE) { # \dontrun{
options(politecollect.user_agent = "my_project (me@example.org)")
res <- openalex_search(
  "works",
  filter = "primary_location.source.issn:0002-8282,publication_year:1990",
  select = "id,doi,title", max_pages = 1
)
res$n_total
} # }