alterlab-openalex

OpenAlex データベース

概要

OpenAlex は、3 億件以上の学術研究成果（デフォルトの「core」コーパス。corpus=all を指定すると、主にデータセットとリポジトリのレコードが加わり、約 60％増加します）、著者、機関、トピック、情報源、出版社、資金提供者を網羅したオープンカタログです。このスキルは、OpenAlex API を検索して文献を探し、研究成果を分析し、引用を追跡し、計量書誌学的研究を行うためのツールとワークフローを提供します。

このスキルを使う場面

• 全分野の学術文献を検索するとき（キーワード、セマンティック検索、または年、OA ステータス、種別による絞り込み）
• OpenAlex／ORCID／ROR／ISSN の ID を使って、著者、機関、資金提供者、情報源の研究成果を探すとき
• 被引用数、引用している研究成果、計量書誌学的分析やトレンド分析（group_by による集計）
• 論文のオープンアクセスのステータスや公開場所を確認するとき、または DOI を一括でメタデータに解決するとき

該当しない場合

シナリオ	代わりに使用
MeSH 用語、PMID、または PubMed Central の全文を使った生物医学文献検索	alterlab-pubmed
起点となる論文を中心とした引用／共引用マップの作成	alterlab-citation-graph
書誌目録のすべての参考文献が実在するか、または撤回済みかの確認	alterlab-citation-verifier
Zotero ライブラリの管理（アイテム、コレクション、添付ファイル）	alterlab-pyzotero
見つかった論文をもとにした、構造化された文献レビューの執筆	alterlab-literature-review

クイックスタート

基本設定

OpenAlex には日次の利用料金上限があります（下記の「レート制限と利用料金」を参照）。認証情報がなくても応答は返されますが、キーなしのリクエストでは、同じ IP アドレスを使う全員で 1 日あたり 0.10 ドルの上限を共有します。大学、VPN、クラウドのネットワークでは上限に達していることが多く、その場合、リストや検索のリクエストはすべて UTC の午前 0 時まで HTTP 429 を返します。無料の API キーを使えば、自分専用の 1 日あたり 1 ドルの上限が適用されます。openalex.org/settings/api で取得し、OPENALEX_API_KEY としてエクスポートしてください。クライアントはキーを読み込み、Authorization: Bearer ヘッダーで送信するため、キーが URL やログに含まれることはありません（?api_key= も使用できます）。以前の mailto による「polite pool」は 2026 年 2 月に廃止されたため、mailto= を指定しても利点はありません。

from scripts.openalex_client import OpenAlexClient

# Recommended: export OPENALEX_API_KEY=...  (free; own $1/day budget)
client = OpenAlexClient()                 # or OpenAlexClient(api_key="...")

# With no key set, the client still works on the shared keyless budget

インストール要件

uv を使って必要なパッケージをインストールします。

uv pip install requests

主な機能

1. 論文を検索する

用途：タイトル、要約、またはトピックから論文を探します。

# Simple search
results = client.search_works(
    search="machine learning",
    per_page=100
)

# Semantic (embedding) search — matches meaning rather than words; accepts up to
# 2,000 characters (e.g. a grant aim), returns at most 50 results, 1 request/second
results = client._make_request('/works', {
    'search.semantic': 'predicting drug toxicity from molecular structure',
    'select': 'id,title,relevance_score',
})

# Search with filters
results = client.search_works(
    search="CRISPR gene editing",
    filter_params={
        "publication_year": ">2020",
        "is_oa": "true"
    },
    sort="cited_by_count:desc"
)

2. 著者の研究成果を探す

用途：特定の研究者による出版物をすべて取得します。

次の 2 段階のパターンを使います（エンティティ名 → ID → 研究成果）。

from scripts.query_helpers import find_author_works

works = find_author_works(
    author_name="Jennifer Doudna",
    client=client,
    limit=100
)

手動で行う 2 段階の方法：

# Step 1: Get author ID
author_response = client._make_request(
    '/authors',
    params={'search': 'Jennifer Doudna', 'per-page': 1}
)
author_id = author_response['results'][0]['id'].split('/')[-1]

# Step 2: Get works
works = client.search_works(
    filter_params={"authorships.author.id": author_id}
)

3. 機関の研究成果を探す

用途：大学や組織の研究成果を分析します。

from scripts.query_helpers import find_institution_works

works = find_institution_works(
    institution_name="Stanford University",
    client=client,
    limit=200
)

4. 被引用数の多い論文

用途：ある分野で影響力のある論文を探します。

from scripts.query_helpers import find_highly_cited_recent_papers

papers = find_highly_cited_recent_papers(
    topic="quantum computing",
    years=">2020",
    client=client,
    limit=100
)

5. オープンアクセス論文

用途：無料で入手できる研究を探します。

from scripts.query_helpers import get_open_access_papers

papers = get_open_access_papers(
    search_term="climate change",
    client=client,
    oa_status="any",  # or "gold", "green", "hybrid", "bronze"
    limit=200
)

6. 出版トレンドの分析

用途：研究成果の推移を追跡します。

from scripts.query_helpers import get_publication_trends

trends = get_publication_trends(
    search_term="artificial intelligence",
    filter_params={"is_oa": "true"},
    client=client
)

# Sort and display
for trend in sorted(trends, key=lambda x: x['key'])[-10:]:
    print(f"{trend['key']}: {trend['count']} publications")

7. 研究成果の分析

用途：著者や機関の研究を包括的に分析します。

from scripts.query_helpers import analyze_research_output

analysis = analyze_research_output(
    entity_type='institution',  # or 'author'
    entity_name='MIT',
    client=client,
    years='>2020'
)

print(f"Total works: {analysis['total_works']}")
print(f"Open access: {analysis['open_access_percentage']}%")
print(f"Top topics: {analysis['top_topics'][:5]}")

8. 一括検索

用途：複数の DOI、ORCID、または ID の情報を効率よく取得します。

dois = [
    "https://doi.org/10.1038/s41586-021-03819-2",
    "https://doi.org/10.1126/science.abc1234",
    # ... any number; sent in batches of 100 (the per-filter OR limit)
]

works = client.batch_lookup(
    entity_type='works',
    ids=dois,
    id_field='doi'
)

9. ランダムサンプリング

用途：分析に使う代表的なサンプルを取得します。

# Small sample
works = client.sample_works(
    sample_size=100,
    seed=42,  # For reproducibility
    filter_params={"publication_year": "2023"}
)

# Large sample (>10k) - automatically handles multiple requests
works = client.sample_works(
    sample_size=25000,
    seed=42,
    filter_params={"is_oa": "true"}
)

10. 引用分析

用途：特定の研究成果を引用している論文を探します。

# Get the work
work = client.get_entity('works', 'https://doi.org/10.1038/s41586-021-03819-2')

# Get citing papers using cited_by_api_url
import requests
citing_response = requests.get(
    work['cited_by_api_url'],
    params={'per_page': 100},
    headers=client.auth_headers(),   # Bearer key, if one is configured
)
citing_works = citing_response.json()['results']

11. トピックと分野の分析

用途：研究の重点分野を把握します。

# Get top topics for an institution
topics = client.group_by(
    entity_type='works',
    group_field='topics.id',
    filter_params={
        "authorships.institutions.id": "I136199984",  # MIT
        "publication_year": ">2020"
    }
)

for topic in topics[:10]:
    print(f"{topic['key_display_name']}: {topic['count']} works")

12. 大規模データの抽出

用途：分析用の大規模なデータセットをダウンロードします。

# Paginate through all results (the client uses cursor paging, so it can go past
# the 10,000-result limit of page-based paging; for whole-corpus pulls use the
# free OpenAlex snapshot instead of the API)
all_papers = client.paginate_all(
    endpoint='/works',
    params={
        'search': 'synthetic biology',
        'filter': 'publication_year:2020-2024'
    },
    max_results=10000
)

# Export to CSV
import csv
with open('papers.csv', 'w', newline='', encoding='utf-8') as f:
    writer = csv.writer(f)
    writer.writerow(['Title', 'Year', 'Citations', 'DOI', 'OA Status'])

    for paper in all_papers:
        writer.writerow([
            paper.get('title', 'N/A'),
            paper.get('publication_year', 'N/A'),
            paper.get('cited_by_count', 0),
            paper.get('doi', 'N/A'),
            paper.get('open_access', {}).get('oa_status', 'closed')
        ])

重要なベストプラクティス

日次の利用上限を増やすには無料の API キーを使う

認証情報がない場合、同じ IP を使う全員で 1 日あたり 0.10 ドルの上限を共有します。無料の API キーを使えば、自分専用の 1 日あたり 1 ドルの上限が適用されます。キーをクライアントに渡します。

export OPENALEX_API_KEY=...   # free at openalex.org/settings/api; OpenAlexClient() picks it up

エンティティの検索には 2 段階のパターンを使う

名前ではなく ID で絞り込みます。名前は曖昧なためです（「Smith」に該当する著者は数千人、「MIT」に該当する機関も複数あります）。まずエンティティを ID に解決してください。

# ✅ Correct
# 1. Search for entity → get ID
# 2. Filter by ID

# ❌ Wrong
# filter=author_name:Einstein  # This doesn't work!

最大ページサイズを使用する

per_page=100 を使用してください（サポートされている最大値です。per_page=200 は非推奨のレガシー動作であり、OpenAlex は削除する予定です）。リスト呼び出しのコストは、結果が1件でも100件でも同じです。

results = client.search_works(search="topic", per_page=100)

複数のIDをまとめて処理する

個別にリクエストするのではなく、複数のIDには batch_lookup() を使用してください。

# ✅ Correct - 1 request per 100 DOIs
works = client.batch_lookup('works', doi_list, 'doi')

# ❌ Wrong - one request per DOI
for doi in doi_list:
    work = client.get_entity('works', doi)

ランダムデータにはサンプルパラメーターを使用する

再現可能なランダムサンプリングには、seed を指定して sample_works() を使用してください。

# ✅ Correct
works = client.sample_works(sample_size=100, seed=42)

# ❌ Wrong - random page numbers bias results
# Using random page numbers doesn't give true random sample

必要なフィールドのみを選択する

特定のフィールドを選択して、レスポンスのサイズを小さくしてください。

results = client.search_works(
    search="topic",
    select=['id', 'title', 'publication_year', 'cited_by_count']
)

よく使うフィルターパターン

filter_params の項目はコンマで結合されます（AND）。構文、演算子、フィールド名の詳細については、references/api_guide.md（Filter Syntax）を参照してください。

filter_params = {
    "publication_year": "2020-2024",        # also "2023", ">2020", "<2020"
    "is_oa": "true",                        # several keys = AND
    "cited_by_count": ">100",
    "authorships.institutions.id": "I136199984|I27837315",   # | = OR (≤100 values): MIT or Harvard
    # "authorships.institutions.id": "I136199984+I27837315", # + = AND within one attribute (co-authored)
    "type": "!paratext",                    # ! = negation
}

エンティティタイプ

OpenAlex が提供するエンティティタイプは次のとおりです。

• works - 学術文書（論文、書籍、データセット）
• authors - ID が曖昧さなく識別された研究者
• institutions - 大学および研究機関
• sources - ジャーナル、リポジトリ、学会
• topics - 分野分類
• publishers - 出版組織
• funders - 資金提供機関

一貫したパターンを使用して、任意のエンティティタイプにアクセスできます。

client.search_works(...)
client.get_entity('authors', author_id)
client.group_by('works', 'topics.id', filter_params={...})

外部ID

外部識別子を直接使用します。

# DOI for works
work = client.get_entity('works', 'https://doi.org/10.7717/peerj.4375')

# ORCID for authors
author = client.get_entity('authors', 'https://orcid.org/0000-0003-1613-5981')

# ROR for institutions
institution = client.get_entity('institutions', 'https://ror.org/02y3ad647')

# ISSN for sources
source = client.get_entity('sources', 'issn:0028-0836')

リファレンスドキュメント

詳細な API リファレンス

以下については、references/api_guide.md を参照してください。

• フィルター構文の全容
• 利用可能なすべてのエンドポイント
• レスポンス構造
• エラー処理
• パフォーマンスの最適化
• レート制限の詳細

よく使うクエリの例

以下については、references/common_queries.md を参照してください。

• 実際に動作する例
• 実用的なユースケース
• 複雑なクエリパターン
• データエクスポートのワークフロー
• 複数ステップの分析手順

スクリプト

openalex_client.py

次の機能を備えたメイン API クライアントです。

• 自動レート制限
• 指数バックオフによる再試行ロジック
• ページネーションのサポート
• バッチ操作
• エラー処理

完全な制御が必要な直接 API アクセスに使用します。

query_helpers.py

一般的な操作向けの高水準ヘルパー関数です。

• find_author_works() - 著者の論文を取得
• find_institution_works() - 機関の論文を取得
• find_highly_cited_recent_papers() - 影響力のある論文を取得
• get_open_access_papers() - OA 出版物を検索
• get_publication_trends() - 時系列の傾向を分析
• analyze_research_output() - 包括的な分析

シンプルなインターフェースで一般的な研究クエリを実行する場合に使用します。

トラブルシューティング

日次上限／スロットリング（429）

429（Too Many Requests）エラーが発生した場合：

1. 共有の API キーなしの予算（1日あたり $0.10）ではなく、自分用の無料 API キー（1日あたり $1）を追加してください（export OPENALEX_API_KEY=...）。Retry-After が数時間を示す429エラーは、日次予算を使い切ったことを意味します。UTC の午前0時までは再試行しても解決せず、その場合クライアントは直ちにエラーを発生させます
2. コストを抑えてください。search=（呼び出しごとのクレジット消費量が多い）よりも、単一エンティティの呼び出しやリスト＋フィルターの呼び出しを優先し、select= を使用してレスポンスのコストを抑えてください
3. 100リクエスト／秒を超えた場合など、短時間のスロットリング（429／403／5xx）に対して、クライアントは自動的にバックオフして再試行します
4. x-ratelimit-remaining-usd／x-ratelimit-cost-usd レスポンスヘッダーを確認し、残りの予算を把握してください

結果が空の場合

検索結果がない場合：

1. フィルター構文を確認してください（references/api_guide.md を参照）
2. エンティティの検索には2段階のパターンを使用してください（名前でフィルターしないでください）
3. エンティティIDの形式が正しいことを確認してください

タイムアウトエラー

大規模なクエリの場合：

1. per_page=100 を使用してページネーションしてください
2. select= を使用して返されるフィールドを絞り込んでください
3. 必要に応じて小さなクエリに分割してください

レート制限とコスト

OpenAlex では、1 日あたりのコスト予算に加え、毎秒 100 リクエストのハード上限が設けられています。各呼び出しには少額の USD コストがかかります。毎日の無料予算があり、それを超えた分のみ支払います（プリペイドのチャージまたは年間プラン）。

• API キーなし：$0.10/日。同じ IP アドレスを使う全員で共有されます。
• 無料 API キーあり（openalex.org/settings/api。Authorization: Bearer <key> または ?api_key= として送信）：自分専用の $1/日。推奨です。mailto= は、丁寧な利用者向けの枠が廃止されたため無視されます（2026 年 2 月）。
• 1,000 回の呼び出しあたりのコスト（help.openalex.org、2026-08）：ID/DOI による単一エンティティの検索は無料、リスト＋フィルターは $0.10、search= は $1、search.semantic= は $1、コンテンツ（PDF）のダウンロードは $10 です。つまり、$1 でフィルター呼び出し約 10,000 回（per_page=100 で約 100 万件の結果）、または検索約 1,000 回を利用できます。可能な場合はフィルターを使ってください。
• クエリ制限：per_page は 100 以下。ページ番号によるページングは 10,000 件で停止します（cursor=* を使用）。フィルターごとの OR 値は 100 個以下。sample は 10,000 以下です。
• GET /rate-limit?api_key=... で残りの予算を確認できます。
• 現在の予算は、レスポンスヘッダー x-ratelimit-limit-usd、x-ratelimit-remaining-usd、x-ratelimit-cost-usd（およびレスポンスの meta.cost_usd）で報告されます。
• 1 日あたりの予算を使い切ると、UTC の午前 0 時までのカウントダウンを示す Retry-After とともに 429 Too Many Requests が返されます。毎秒 100 リクエストを超えるバーストでも 429 が返されます（短時間の待機）。403 が「速度を落としてください」という意味の場合もあります。

注意事項

• すべてのデータは公開されており、無料です。通常の研究ワークロードには、1 日あたりの予算で十分対応できます。
• ある程度以上の規模のワークフローでは、無料 API キーの使用を推奨します。単発の検索なら、API キーなしでも問題ありません。
• コストと制限は、リクエストの種類ごとではなく、認証情報ごと（キー単位、キーなしの場合は IP 単位）に適用されます。search= を最小限にし、select= を使って予算を有効活用してください。
• LLM による分析が必要な場合は、OpenRouter とともに LitLLM を使用してください（Perplexity API を直接使用しないでください）。
• クライアントがページネーション、再試行、バックオフを自動的に処理します。