@univ-lehavre/atlas-fetch-openalex

Central OpenAlex API client for the Atlas monorepo. Provides typed Effect-based functions for institutions, works, and authors — with api_key authentication and rate-limit header support.

Installation

pnpm add @univ-lehavre/atlas-fetch-openalex

Configuration

import type { OpenAlexConfig } from '@univ-lehavre/atlas-fetch-openalex';

const config: OpenAlexConfig = {
  userAgent: 'my-app/1.0 (mailto:contact@example.com)',
  apiKey: process.env.OPENALEX_API_KEY,   // optional
  apiURL: 'https://api.openalex.org',     // optional, default
};

API

Institutions

searchInstitutions(query, config)

Searches institutions via the OpenAlex autocomplete endpoint.

import { searchInstitutions } from '@univ-lehavre/atlas-fetch-openalex';
import { Effect } from 'effect';

const result = await Effect.runPromise(searchInstitutions('Le Havre', config));
// result.institutions: Institution[]
// result.rateLimit?: RateLimitInfo

Works

getWorksCount(institutionIds, config)

Returns the count of articles from selected institutions over the last 5 years.

const result = await Effect.runPromise(
  getWorksCount(['https://openalex.org/I123'], config)
);
// result.count, result.fromDate, result.rateLimit?

getInstitutionStats(institutionIds, config)

Fetches works count, articles by year, and authors count in 3 parallel requests.

const stats = await Effect.runPromise(
  getInstitutionStats(['https://openalex.org/I123'], config)
);
// stats.worksCount, stats.articlesCount, stats.articlesByYear, stats.authorsCount

Authors

Function	Description
searchAuthorsByName(names, config)	Search authors by display name
searchAuthorsByORCID(orcids, config)	Search authors by ORCID
searchWorksByAuthorIDs(ids, config)	Fetch works by author OpenAlex IDs
searchWorksByORCID(orcid, config)	Fetch works by author ORCID
searchWorksByDOI(dois, config)	Fetch works by DOI

Pagination (advanced)

For cursor-paginated requests across multiple pages:

Export	Description
fetchAPIResults<T>(opts)	Fetches all pages and returns results array
fetchAPIQueue<T>(opts)	Fetches into a queue for streaming
FetchAPIMinimalConfig	Configuration type for paginated requests

Classes

Class	Description
Store	-

Interfaces

Interface	Description
APIResponse	-
FetchAPIConfig	-
Institution	-
InstitutionSearchResult	-
InstitutionStatsResult	-
IState	-
OpenAlexConfig	-
RateLimitInfo	-
WorksCountResult	-
YearlyArticleCount	-

Type Aliases

Type Alias	Description
FetchAPIMinimalConfig	-

Variables

Variable	Description
initialState	-

Functions

Function	Description
fetchAPIQueue	-
fetchAPIResults	-
getInstitutionStats	Gets comprehensive statistics for selected institutions. Fetches works count, articles by year, and authors count in parallel.
getWorksCount	Gets the count of articles from selected institutions over the last N years.
searchAuthorsByName	Searches for authors by display name.
searchAuthorsByORCID	Searches for authors by ORCID.
searchInstitutions	Searches for institutions using the OpenAlex autocomplete API.
searchWorksByAuthorID	Searches for works by a single author OpenAlex ID. Prefer this over searchWorksByAuthorIDs when fetching for multiple authors, as the multi-ID filter is unreliable with many IDs.
searchWorksByAuthorIDs	Searches for works by author OpenAlex IDs.
searchWorksByDOI	Searches for works by DOI.
searchWorksByORCID	Searches for works by author ORCID.