OpenAlex Database

概要

OpenAlex は 240M 以上の学術論文、著者、機関、トピック、情報源、出版社、資金提供者からなる包括的なオープンカタログです。このスキルは OpenAlex API をクエリするためのツールとワークフローを提供し、文献検索、研究出力の分析、引用の追跡、および書誌計量学的研究を実施できます。

クイックスタート

基本セットアップ

常にメールアドレスでクライアントを初期化して、丁寧プール (レート制限 10 倍ブースト) にアクセスしてください:

from scripts.openalex_client import OpenAlexClient

client = OpenAlexClient(email="your-email@example.edu")

インストール要件

uv を使用して必要なパッケージをインストールしてください:

uv pip install requests

API キーは不要です - OpenAlex は完全にオープンです。

コア機能

1. 論文を検索

用途: タイトル、アブストラクト、またはトピックで論文を検索

# シンプルな検索
results = client.search_works(
    search="machine learning",
    per_page=100
)

# フィルター付き検索
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 段階アプローチ:

# ステップ 1: 著者 ID を取得
author_response = client._make_request(
    '/authors',
    params={'search': 'Jennifer Doudna', 'per-page': 1}
)
author_id = author_response['results'][0]['id'].split('/')[-1]

# ステップ 2: 論文を取得
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",  # または "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
)

# ソートして表示
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',  # または '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",
    # ... 最大 50 個の DOI
]

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

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

用途: 分析用の代表的なサンプルを取得

# 小規模サンプル
works = client.sample_works(
    sample_size=100,
    seed=42,  # 再現性のため
    filter_params={"publication_year": "2023"}
)

# 大規模サンプル (>10k) - 複数のリクエストを自動処理
works = client.sample_works(
    sample_size=25000,
    seed=42,
    filter_params={"is_oa": "true"}
)

10. 引用分析

用途: 特定の論文を引用している論文を検索

# 論文を取得
work = client.get_entity('works', 'https://doi.org/10.1038/s41586-021-03819-2')

# cited_by_api_url を使用して引用論文を取得
import requests
citing_response = requests.get(
    work['cited_by_api_url'],
    params={'mailto': client.email, 'per-page': 200}
)
citing_works = citing_response.json()['results']

11. トピックと主題分析

用途: 研究焦点領域を理解

# 機関のトップトピックを取得
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. 大規模データ抽出

用途: 分析用の大規模データセットをダウンロード

# すべての結果をページネーション処理
all_papers = client.paginate_all(
    endpoint='/works',
    params={
        'search': 'synthetic biology',
        'filter': 'publication_year:2020-2024'
    },
    max_results=10000
)

# 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')
        ])

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

常にメールを使用して丁寧プールを利用

メールを追加してレート制限 10 倍を取得 (1 req/秒 → 10 req/秒):

client = OpenAlexClient(email="your-email@example.edu")

エンティティ検索に 2 段階パターンを使用

エンティティ名で直接フィルタリングしないでください - 常に最初に ID を取得してください:

# ✅ 正解
# 1. エンティティを検索 → ID を取得
# 2. ID でフィルタリング

# ❌ 誤り
# filter=author_name:Einstein  # これは機能しません!

最大ページサイズを使用

効率的なデータ取得のため常に per-page=200 を使用してください:

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

複数の ID をバッチ処理

個別のリクエストの代わりに batch_lookup() を使用してください:

# ✅ 正解 - 50 個の DOI に対して 1 つのリクエスト
works = client.batch_lookup('works', doi_list, 'doi')

# ❌ 誤り - 50 個の個別リクエスト
for doi in doi_list:
    work = client.get_entity('works', doi)

ランダムデータには Sample パラメータを使用

再現可能なランダムサンプリングのために sample_works() とシードを使用してください:

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

# ❌ 誤り - ランダムページ番号はバイアスのある結果をもたらす
# ランダムページ番号を使用することは、真のランダムサンプルを提供しません

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

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

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

一般的なフィルターパターン

日付範囲

# 単一年
filter_params={"publication_year": "2023"}

# 年以降
filter_params={"publication_year": ">2020"}

# 範囲
filter_params={"publication_year": "2020-2024"}

複数フィルター (AND)

# すべての条件が合致する必要がある
filter_params={
    "publication_year": ">2020",
    "is_oa": "true",
    "cited_by_count": ">100"
}

複数値 (OR)

# いずれかの機関が合致
filter_params={
    "authorships.institutions.id": "I136199984|I27837315"  # MIT または Harvard
}

コラボレーション (属性内の AND)

# BOTH 機関の著者による論文
filter_params={
    "authorships.institutions.id": "I136199984+I27837315"  # MIT AND Harvard
}

否定

# タイプを除外
filter_params={
    "type": "!paratext"
}

エンティティタイプ

OpenAlex は以下のエンティティタイプを提供します:

• works - 学術文献 (記事、書籍、データセット)
• authors - 曖昧性を排除した研究者
• institutions - 大学と研究機関
• sources - ジャーナル、リポジトリ、会議
• topics - 主題分類
• publishers - 出版組織
• funders - 資金提供機関

一貫したパターンを使用して任意のエンティティタイプにアクセスしてください:

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

外部 ID

外部識別子を直接使用してください:

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

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

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

# 情報源の ISSN
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() - 包括的な分析

簡潔なインターフェースで一般的な研究クエリに使用してください。

トラブルシューティング

レート制限

403 エラーが発生した場合:

1. メールがリクエストに追加されていることを確認してください
2. 10 req/秒を超えていないことを確認してください
3. クライアントは自動的に指数バックオフを実装します

空の結果

検索に結果が返されない場合:

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

タイムアウトエラー

大規模クエリの場合:

1. per-page=200 でページネーションを使用してください
2. select= を使用して返されるフィールドを制限してください
3. 必要に応じてより小さなクエリに分割してください

レート制限

• デフォルト: 1 リクエスト/秒、100k リクエスト/日
• 丁寧プール (メール付き): 10 リクエスト/秒、100k リクエスト/日

本番ワークフローではクライアントにメールを提供して丁寧プールを常に使用してください。

注記

• 認証不要
• すべてのデータはオープンかつ無料
• レート制限はグローバルに適用されます (IP ごとではありません)
• LLM ベースの分析が必要な場合は LitLLM と OpenRouter を使用してください (Perplexity API を直接使用しないでください)
• クライアントがページネーション、再試行、およびレート制限を自動的に処理します