npm package: @openpets/openalex
Description: Access scholarly research data from OpenAlex including works, authors, institutions, journals, and research concepts. Search and retrieve academic publications, citations, and metadata.
Latest version: 1.0.2

# OpenAlex Pet

> **✅ Working Implementation**: This pet uses a custom OpenAPI specification created from the official API documentation. All 21 auto-generated tools are fully functional. See [Custom OpenAPI Spec](#custom-openapi-specification) for details.

Access scholarly research data from the OpenAlex API, including works, authors, institutions, sources (journals/repositories), topics, publishers, and funders.

## Overview

OpenAlex is a free, open catalog of the world's scholarly research system. This pet provides access to:

- **Works** - Academic publications and their metadata
- **Authors** - Researcher profiles (searchable by ORCID)
- **Institutions** - Universities and research organizations (searchable by ROR)
- **Journals** - Academic journals and venues (searchable by ISSN)
- **Concepts** - Research topics and subject classifications

All tools are auto-generated from the OpenAlex OpenAPI specification.

## Quick Start

### 1. Get an API Key

Visit [openalex.org/settings/api](https://openalex.org/settings/api) to get a free API key.

- **Free tier**: 100,000 credits per day
- **Single lookups**: 1 credit per request
- **List queries**: 10 credits per page

### 2. Configure Environment

Create a `.env` file:

```bash
OPENALEX_API_KEY=your_api_key_here

# Optional: Add your email for "polite pool" access (better rate limits)
OPENALEX_EMAIL=your.email@example.com
```

### 3. Test Connection

```bash
opencode run "test openalex connection" --print-logs
```

## Available Tools

All 21 tools are auto-generated from a custom OpenAPI specification based on the current API:

### Works (3 tools)
- `openalex-get-work-by-id` - Get work by OpenAlex ID (e.g., W2741809807)
- `openalex-get-work-by-doi` - Get work by DOI (e.g., 10.1371/journal.pone.0266781)
- `openalex-list-works` - Search and filter works with full-text search

### Authors (3 tools)
- `openalex-get-author-by-id` - Get author by OpenAlex ID (e.g., A5023888391)
- `openalex-get-author-by-orcid` - Get author by ORCID (e.g., 0000-0003-1613-5981)
- `openalex-list-authors` - Search and filter authors

### Sources (3 tools)
- `openalex-get-source-by-id` - Get source by OpenAlex ID (e.g., S137773608)
- `openalex-get-source-by-issn` - Get source by ISSN (e.g., 0028-0836)
- `openalex-list-sources` - Search and filter journals, repositories, conferences

### Institutions (3 tools)
- `openalex-get-institution-by-id` - Get institution by OpenAlex ID (e.g., I136199984)
- `openalex-get-institution-by-ror` - Get institution by ROR (e.g., 02y3ad647)
- `openalex-list-institutions` - Search and filter institutions

### Topics (2 tools)
- `openalex-get-topic-by-id` - Get topic by OpenAlex ID (e.g., T10178)
- `openalex-list-topics` - Search and filter research topics

### Publishers (2 tools)
- `openalex-get-publisher-by-id` - Get publisher by OpenAlex ID (e.g., P4310319900)
- `openalex-list-publishers` - Search and filter publishers

### Funders (2 tools)
- `openalex-get-funder-by-id` - Get funder by OpenAlex ID (e.g., F4320332161)
- `openalex-list-funders` - Search and filter funding agencies

### Autocomplete (3 tools - requires env var)
Enable with `OPENALEX_LOAD_AUTOCOMPLETE_TOOLS=true`:
- `openalex-autocomplete-works` - Autocomplete works for search interfaces
- `openalex-autocomplete-authors` - Autocomplete authors
- `openalex-autocomplete-institutions` - Autocomplete institutions

## Example Queries

```bash
# Test connection
opencode run "test openalex connection"

# Look up a work by DOI
opencode run "get work by DOI 10.1371/journal.pone.0266781"

# Look up an author by ORCID
opencode run "get author by ORCID 0000-0003-1613-5981"

# Search for works about machine learning
opencode run "search for recent works about machine learning"

# Look up an institution by ROR
opencode run "get institution by ROR 02y3ad647"

# Look up a journal by ISSN
opencode run "get source by ISSN 0028-0836"

# Find works from MIT
opencode run "search institutions for MIT then find recent works from them"
```

## Identifier Types

OpenAlex uses several identifier systems:

| Type | Example | Description |
|------|---------|-------------|
| **OpenAlex ID** | `A2741809807` | Internal OpenAlex identifier |
| **ORCID** | `0000-0001-6187-6610` | Open Researcher and Contributor ID |
| **DOI** | `10.1038/nature12373` | Digital Object Identifier |
| **ROR** | `02y3ad647` | Research Organization Registry |
| **ISSN** | `0028-0836` | International Standard Serial Number |
| **PMID** | `23719680` | PubMed ID |

## Rate Limits

The OpenAlex API has generous rate limits:

- **Free tier**: 100,000 credits/day
- **Polite pool** (with email): Higher priority and better performance
- **Credits per operation**:
  - Single entity lookup: 1 credit
  - List query (per page): 10 credits
  - Semantic search: 1,000 credits

Set `OPENALEX_EMAIL` to join the polite pool for better performance.

## Regenerating Tools

When the OpenAlex API updates, regenerate the tools:

```bash
cd pets/openalex
pets generate-openapi --verbose
```

This will fetch the latest OpenAPI spec and regenerate `openapi-client.ts`.

## Configuration

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `OPENALEX_API_KEY` | Yes | API key from openalex.org/settings/api |
| `OPENALEX_EMAIL` | No | Your email for polite pool access |
| `OPENALEX_HOST` | No | Override base URL (default: https://api.openalex.org) |

### OpenAPI Configuration

Defined in `package.json`:

```json
{
  "openapiSpec": {
    "url": "https://raw.githubusercontent.com/ourresearch/openalex-api-docs/...",
    "baseUrl": "https://api.openalex.org",
    "authType": "apiKey",
    "apiKeyHeader": "X-API-Key",
    "authEnvVar": "OPENALEX_API_KEY"
  }
}
```

## Resources

- [OpenAlex Documentation](https://docs.openalex.org)
- [OpenAlex API Guide for LLMs](https://docs.openalex.org/api-guide-for-llms)
- [Get API Key](https://openalex.org/settings/api)
- [OpenAPI Specification](https://github.com/ourresearch/openalex-api-docs)

## Custom OpenAPI Specification

**This pet uses a custom OpenAPI specification** created from the official API documentation because OpenAlex's official spec is outdated (last updated Dec 2021).

### What's Included

The custom spec (`openapi-spec.yaml`) includes:

**✅ Current API Structure:**
- Correct paths: `/works/`, `/authors/`, `/sources/`, `/institutions/`, `/topics/`, `/publishers/`, `/funders/`
- External ID lookups: `/works/https://doi.org/{doi}`, `/authors/https://orcid.org/{orcid}`, etc.
- Query parameters: `search`, `filter`, `sort`, `per-page`, `page`
- Autocomplete endpoints for building search interfaces

**✅ All 7 Entity Types:**
- Works (240M+ scholarly documents)
- Authors (researcher profiles)
- Sources (journals, repositories, conferences)
- Institutions (universities, research organizations)
- Topics (3-level subject hierarchy)
- Publishers (publishing organizations)
- Funders (funding agencies)

**✅ Generated from Official Docs:**
- Based on [API Guide for LLMs](https://docs.openalex.org/api-guide-for-llms)
- Matches current API behavior (tested Feb 2026)
- Supports all common use cases

### Why We Created This

OpenAlex's official OpenAPI spec:
- **Last Updated**: December 8, 2021 (3+ years ago)
- **Problems**: Uses outdated paths (`/work/` vs `/works/`), missing entities (`sources`), wrong ID formats
- **Status**: Not hosted on API, appears unmaintained

**Example of the problem:**
```bash
# Official spec path (404 error)
curl "https://api.openalex.org/work/doi/10.1038/nature12373"

# Actual API (works)
curl "https://api.openalex.org/works/https://doi.org/10.1038/nature12373"
```

Our custom spec fixes all these issues and enables the full OpenAPI generation workflow.

### Benefits of Custom Spec

1. **Working Tools**: All 21 generated tools work correctly with the current API
2. **Comprehensive Coverage**: All 7 entity types with get, list, and search operations
3. **OpenPets Workflow**: Demonstrates complete OpenAPI generation process
4. **Maintainable**: Easy to update when API changes
5. **Documented**: Includes descriptions, examples, and parameter details

### Regenerating Tools

If the API changes, update the spec and regenerate:

```bash
cd pets/openalex
pets generate-openapi --verbose
```

The spec file is `openapi-spec.yaml` in this directory.

### Contributing Back

We've documented the issues with the official spec in `OPENAPI_ISSUES.md`. If you'd like to help OpenAlex:

1. File an issue: https://github.com/ourresearch/openalex-docs/issues
2. Contact support: support@openalex.org
3. Share this working spec as a reference

## Troubleshooting

### "API key not set"

Make sure you've set `OPENALEX_API_KEY` in your `.env` file. Get a free key at [openalex.org/settings/api](https://openalex.org/settings/api).

### Rate limit errors

If you're hitting rate limits:

1. Set `OPENALEX_EMAIL` to join the polite pool
2. Check your daily credit usage
3. Consider adding delays between requests

### Invalid identifier format

Different lookups require different identifier formats:

- **ORCID**: Format `0000-0001-2345-6789` (with dashes)
- **DOI**: Full DOI like `10.1038/nature12373`
- **ROR**: ROR ID like `02y3ad647`
- **ISSN**: Format `0028-0836` or `2041-1723`

## Development

This pet uses the OpenAPI generation workflow:

1. **OpenAPI spec** → `package.json` openapiSpec configuration
2. **Generate** → `pets generate-openapi` creates `openapi-client.ts`
3. **Import** → `index.ts` imports and combines with test-connection tool

For more details, see [docs/openapi-generation.md](../../docs/openapi-generation.md).