openalex-database

OpenAlex データベース

概要

OpenAlex は、240M 件を超える学術論文、著者、機関、トピック、ソース、出版社、資金提供機関を収録する包括的なオープンカタログです。このスキルは、OpenAlex API に対するクエリを実行し、文献検索、研究成果の分析、被引用数の追跡、書誌計量学的研究を行うためのツールとワークフローを提供します。

クイックスタート

基本設定

polite pool（レート制限が 10 倍に拡大）にアクセスするため、必ずメールアドレスを指定してクライアントを初期化してください：

from scripts.openalex_client import OpenAlexClient

client = OpenAlexClient(email="[email protected]")

インストール要件

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

uv pip install requests

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

主な機能

1. 論文の検索

用途：タイトル、抄録、トピックによる論文の検索

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

# 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",
    # ... up to 50 DOIs
]

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={'mailto': client.email, 'per-page': 200}
)
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
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')
        ])

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

polite pool のためにメールアドレスを必ず使用する

メールアドレスを追加すると、レート制限が 10 倍になります（1 リクエスト/秒 → 10 リクエスト/秒）：

client = OpenAlexClient(email="[email protected]")

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

エンティティ名で直接フィルタリングしないでください。必ず先に ID を取得してください：

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

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

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

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

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

複数の ID をまとめて指定する

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

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

# ❌ Wrong - 50 separate requests
for doi in doi_list:
    work = client.get_entity('works', doi)

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

再現可能なランダムサンプリングには、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']
)

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

日付範囲

# Single year
filter_params={"publication_year": "2023"}

# After year
filter_params={"publication_year": ">2020"}

# Range
filter_params={"publication_year": "2020-2024"}

複数フィルター（AND）

# All conditions must match
filter_params={
    "publication_year": ">2020",
    "is_oa": "true",
    "cited_by_count": ">100"
}

複数の値（OR）

# Any institution matches
filter_params={
    "authorships.institutions.id": "I136199984|I27837315"  # MIT or Harvard
}

共著（属性内の AND）

# Papers with authors from BOTH institutions
filter_params={
    "authorships.institutions.id": "I136199984+I27837315"  # MIT AND Harvard
}

否定

# Exclude type
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 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() - 包括的な分析

簡略化されたインターフェースで一般的な研究クエリに使用します。

トラブルシューティング

レート制限

403 エラーが発生する場合:

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

結果が空の場合

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

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

タイムアウトエラー

大規模なクエリの場合:

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

レート制限

• デフォルト: 1 リクエスト/秒、1 日あたり 10 万リクエスト
• ポライトプール(メールアドレス付き): 10 リクエスト/秒、1 日あたり 10 万リクエスト

本番ワークフローでは、必ずクライアントにメールアドレスを指定してポライトプールを使用してください。

注意事項

• 認証は不要です
• すべてのデータはオープンで無料です
• レート制限は IP アドレスごとではなく、全体に適用されます
• LLM ベースの分析が必要な場合は、OpenRouter を使用した LitLLM を使用してください(Perplexity API を直接使用しないでください)
• クライアントはページネーション、リトライ、レート制限を自動的に処理します