aminer-academic-search

AMiner オープンプラットフォーム学術データクエリ

30 個の API ＋ 6 個のワークフロー。トークンが必要です：AMINER_API_KEY 環境変数を設定してください。

• ドキュメント：https://open.aminer.cn/open/docs | コンソール：https://open.aminer.cn/open/board?tab=control

---

必須ルール（重要）

1. トークンのセキュリティ：AMINER_API_KEY が存在するかどうかだけを確認してください。トークンを平文で公開してはいけません。
2. コスト管理：最適な組み合わせクエリを優先し、詳細情報を無差別に取得してはいけません。ユーザーが件数を指定していない場合、詳細情報はデフォルトで上位 10 件とします。
3. 無料優先：ユーザーがより詳細なフィールドを明示的に必要としている場合を除き、無料 API を優先してください。無料 API では要件を満たせない場合に限り、有料 API に切り替えてください。
4. 結果リンク：出力内の各エンティティの後には、必ずアクセス可能な URL を付けてください。
5. 曖昧性の解消：研究者が曖昧な場合は、org／org_id で絞り込むか、ユーザーに確認してください。組織が曖昧な場合は、org_disambiguate_pro を使用してください。論文が曖昧な場合は、year ＋ venue_name ＋ first_author を照合してください。
6. コスト報告：すべての API 呼び出しが完了した後、各 API、単価、呼び出し回数、合計コストを含むコスト概要を必ずユーザーに出力してください。書式例：[Cost] ¥X.XX total, N API calls (api_a: ¥X.XX × N, api_b: Free × N)。
7. 高額な処理の確認（¥5 以上）：推定合計コストが ¥5.00 以上となるワークフローまたは一連の呼び出しを実行する前に、停止してユーザーに確認を求めてください。予定している呼び出しの流れ、各ステップの推定コスト、合計額を提示してください。ユーザーが明示的に同意した後にのみ続行してください。これは、事前定義されたワークフロー（例：研究者プロフィール ~¥6.50）と、その場で組み立てる複数ステップの計画の両方に適用されます。
8. 実験データに関する意図の境界：experiment_search を呼び出すのは、ユーザーが実験レベルのデータ、Experiment JSON、手法、データセット、または構造化された実験結果を明示的に求めた場合に限ります。通常の論文検索、要旨／引用の検索、研究者／組織／会場／特許に関するリクエスト、広範なトピック検索、またはデフォルトの Paper Deep Dive ワークフローに追加してはいけません。

エンティティ URL テンプレート（必須）：

• 論文：https://www.aminer.cn/pub/{paper_id}
• 研究者：https://www.aminer.cn/profile/{scholar_id}
• 特許：https://www.aminer.cn/patent/{patent_id}
• ジャーナル：https://www.aminer.cn/open/journal/detail/{journal_id}

---

トークンの確認（必須）

API を呼び出す前に、AMINER_API_KEY が存在することを確認してください。トークンを平文で公開してはいけません。

[ -z "${AMINER_API_KEY+x}" ] && echo "AMINER_API_KEY missing" || echo "AMINER_API_KEY exists"

• ${AMINER_API_KEY} が存在する場合は続行してください。存在しない場合は、--token パラメーターを確認してください。どちらもない場合は、停止し、トークンを生成するためにコンソールを利用するようユーザーに案内してください。
• ユーザーが AMINER_API_KEY をインラインで提供した場合（例：「私のトークンは xxx です」）、現在のセッションでは受け付けますが、セキュリティ向上のため環境変数として設定することを推奨してください。
• デフォルトのヘッダー：Authorization: ${AMINER_API_KEY}、X-Platform（現在のホスト：claude-code／cursor／codex／openclaw。判別できない場合は unknown）、X-Skill-Name: aminer-academic-search、X-Skill-Version（このファイルの frontmatter の version）、Content-Type: application/json;charset=utf-8（POST）。X-Platform と 2 つの X-Skill-* ヘッダーは必ず送信してください。

---

呼び出しのガードレール

1. パラメーター名と型は、references/api-catalog.md と完全に一致させてください。
2. paper_info（無料のカード）と paper_detail（詳細情報。取得した論文1件あたり¥0.01）は、どちらも {"ids": [...]}（≤100）を受け取ります。1件ずつ呼び出すのではなく、複数の論文の詳細を1回の paper_detail 呼び出しで取得してください。
3. 複数の詳細情報が必要な場合は、まず低コストのAPIで絞り込んでから、少数の論文の詳細を取得してください。
4. 検索の階段は一段ずつ上ってください。「論文検索APIの選択ガイド」を参照してください。無料の paper_search から始め、現在の階層にないパラメーターが必要な場合にのみ上位に進んでください。¥0.30の paper_qa_search_pro に費用をかける前に、4つの理由のいずれか（複雑な質問、引用数の範囲、ブール式による除外、精度優先）を挙げられる必要があります。挙げられない場合は、下位の階層に戻ってください。年の範囲は理由にはなりません。paper_search と paper_search_pro はどちらも year_from／year_to を受け取ります。

---

論文検索APIの選択ガイド

4つの論文検索エンドポイントは、アップグレードの階段を構成しています。必要なパラメーターを備えた最も低い階層を選んでください。

階層	API	提供機能	厳格な上限	費用
1	paper_search	検索ボックス query 1つ（タイトル＋キーワード）、year／year_from／year_to	1ページ≤20件、最大10ページ。フィールドごとの条件指定や並べ替えは不可	無料
2	paper_search_pro	階層1のすべてに加え、フィールドごとの title／keyword／abstract／author／org／venue、order=year|n_citation、1ページ≤100件 — 大量取得で最安	—	¥0.01
3	paper_qa_search	query からサーバー側で抽出するキーワード、重み付きの topic_high/middle/low、著者／組織／会場のIDフィルター、doi、sci_flag、offset ≤ 10000	指定できるのは year のリストのみで、範囲指定は不可。ブール式による除外は不可	¥0.05
4	paper_qa_search_pro	自然言語の理解、年と引用数の範囲、all/any/exclude、sort モード、authors の全リスト、最良の検索精度	1ページあたり固定10件。以降の各ページでさらに¥0.30	¥0.30
—	paper_list_by_keywords	テーマ別の一括取得	—	¥0.10
—	paper_detail_by_condition	年＋会場で絞り込み、詳細情報を直接返す	—	¥0.20

アップグレードのルール

1. paper_search から始めてください。 フレーズ、既知のタイトル、短い文章はいずれも検索結果を返します。期間を指定するには year_from／year_to を追加してください。
2. フィールドごとの条件（著者、機関、会場、抄録）、並べ替え、または1ページあたり20件を超える結果が必要ですか？ → paper_search_pro。
3. 著者／組織／会場のIDフィルター、DOI、SCIのみ、または重み付きトピックの階層が必要ですか？ → paper_qa_search。
4. 複雑な質問の意図を理解する機能、引用数の範囲、ブール式による除外、または精度優先が必要ですか？ → paper_qa_search_pro。

費用の差に注意してください。 100件の結果を得る場合、paper_search_pro は size=100 で1回呼び出せば¥0.01ですが、paper_qa_search_pro ではカーソルページを10回取得する必要があり、¥3.00かかります。300倍です。 件数が多い場合は、階層4を決して使わないでください。

¥0.30を使う際の厳格なルール

paper_qa_search_pro を呼び出す前に、次の理由の少なくとも1つを挙げられる必要があります。挙げられない場合は、下位の階層に戻ってください。

1. 複雑な質問 — 用語の一致では意味を捉えられない自然言語の質問（複数の概念や関係を含むもの、口語表現や中国語の表現など）、またはより安価な階層で検索した結果、質問の意図から外れていた場合。
2. 引用数の範囲 — min_citations／max_citations が必要な場合。（paper_search／paper_search_pro では年の範囲を指定できます。年の範囲は理由になりません。）
3. ブール式による除外 — all_terms／any_terms／exclude_terms が必要な場合。
4. 精度優先 — ユーザーが正確な結果、または最も一致度の高い結果を明示的に求めている場合。how do LLM agents implement long-term memory での比較では、Proはエージェントの長期記憶を具体的に扱う結果を4件中4件返しましたが、従来の paper_qa_search では5件中1件でした。

4つの理由のどれにも当てはまらない場合は、何も得られないのに30倍の費用を払うことになります。下位の階層に戻ってください。 paper_qa_search_pro の主なルール：

• 自然言語の query フィールドを使用してください（デフォルトの query_type="auto"）。ユーザーの質問を元のまま、完全な文として渡してください。キーワードに事前分割して all_terms に再構成しないでください。分割すると、料金を払って利用している意味理解が失われ、精度が単に質問するよりも低下します。文字どおりの用語一致が本当に必要な場合に限り、query_type="topic" に切り替えてください。
• ページサイズは10で固定です。size は送信しないでください。next_cursor でページ送りし、次のリクエスト本文は {"cursor":"..."} のみとします。
• sort：relevance／balanced／recent／citation。「最も引用されている論文」には citation、「最新の論文」には recent を使用してください。
• レスポンスのカードに含まれるフィールドのみ：paper_id、title、title_zh、doi、authors.name／name_zh、n_citation_bucket、venue_name、year。完全な要旨／キーワード、または正確な引用数（n_citation）が必要な場合は paper_detail を使用してください。
• 必ず https://www.aminer.cn/pub/{paper_id} を末尾に追加してください。

paper_qa_search の主なルール：

• 重み付きの入れ子 AND／OR：topic_high／topic_middle／topic_low で3段階のブーストを指定できます。Pro には同等の機能がありません。「Aを必須とし、Bを強くブーストし、Cを弱くブースト」する場合に使用してください。
• 深いページ送り：size は ≤ 100、offset は ≤ 10000 です。¥0.05で100件取得でき、これは paper_qa_search_pro のカーソル（1ページ10件 × ¥0.30）では及びません。件数だけが必要なら paper_search_pro のほうがさらに安価です（100件あたり¥0.01）。
• sci_flag は SCI 論文に絞り込みます。Pro にはこのフィルターがありません。
• query と topic_high/topic_middle/topic_low は併用できません。両方を渡さないでください。query と topic_* には use_topic: true が必要です。
• レスポンスには doi、first_author、venue_name、venue_id、year、n_citation_bucket が含まれます。paper_detail を呼び出して料金を払う前に、これらのフィールドで絞り込んでください。

実験検索の選択：

• 実験単位の検索意図が明示されている場合に限り、experiment_search を使用してください（1回あたり¥0.10）。
• 完全一致フィルター：paper_id、method、dataset_name（→ バックエンドの dataset）。
• 自由文（論文タイトル、実験名、課題／手法／結論など）には search_text を使用してください（paper_title、experiment_name、research_problem、research_problem_description、research_goal、手法名／説明文、conclusion、limitations、key_results を対象にした ES 検索）。
• レスポンス形式：各結果には methods: [{name, description, ...}]（リスト）が含まれます。古いレコードの一部には、フラットな method／method_description が残っている場合があります。オブジェクトはそのまま返してください。まず methods を確認し、リストを単一の method 文字列にフラット化しないでください。
• タイトルの解決に paper_search を呼び出さないでください。独立した experiment_name パラメーターも送信しないでください。
• paper_id、method、dataset_name、search_text のうち、少なくとも1つは空でない値にしてください。トリミングのみとし、フィールドを捏造しないでください。
• Raw JSON リクエストは Experiment オブジェクトを書き換えず、{ "results": [...] } を返します。

無料枠で利用できるスクリーニング用フィールド：

• paper_search：doi、venue_name、first_author、n_citation_bucket、year
• paper_info：abstract_slice、year、venue_id、author_count
• person_search：interests、n_citation、org/org_id
• organization_search：aliases
• venue_search：aliases、venue_type
• patent_search：inventor_name、app_year、pub_year
• patent_info：app_year、pub_year

paper_search、paper_search_pro、paper_qa_search は同じスクリーニング項目（doi、first_author、venue_name、year、n_citation_bucket）を返します。paper_qa_search はさらに venue_id（リンクされている場合の会場エンティティ ID。会場 API に渡せます）を返します。paper_qa_search_pro は authors リスト全体に加えて、doi、venue_name、year、n_citation_bucket を返します。paper_detail を呼び出す前に、これらの項目で絞り込んでください（返された論文1件あたり¥0.01。見つからない ID は無料）。実際に引用する論文の詳細だけを、1回の呼び出しで取得してください。n_citation_bucket は大まかな段階を示す値であり、正確な件数ではありません。バケットを数値として比較したり、そこから正確な引用数を主張したりしないでください。正確な n_citation は paper_detail が返します。

ワークフロー外のリクエストへの対応

ユーザーのリクエストが6つのワークフローに当てはまらない場合：

1. references/api-catalog.md を読み、利用可能な API、パラメーター、レスポンスフィールドを確認します。
2. 実行可能な最短の呼び出しチェーンを設計します：ID を特定 → 詳細を補完 → 関連情報を展開。
3. 「既存のワークフローに当てはまらない」からといって諦めず、api-catalog に基づいて API を積極的に組み合わせます。

---

6つの複合ワークフロー

ワークフロー1：研究者プロフィール（約¥6.50）

ユースケース：経歴、指標、研究関心、論文、特許、プロジェクトを含む包括的な学術プロフィール。 費用に関する注意：すべて実行すると¥5のしきい値を超えるため、進める前に必ずユーザーの確認を求めてください（ルール7）。予定している手順と費用を示してください。必要なサブモジュールを確認し、依頼されていない場合は特許／プロジェクトを省略します。

呼び出しチェーン：

Scholar search (name → person_id)
    ↓
Parallel calls (pick as needed):
  ├── Scholar details (bio/education/honors)         ¥1.00
  ├── Scholar statistics (h-index/g-index/citations) ¥0.50
  ├── Scholar portrait (interests/work history)      ¥0.50
  ├── Scholar papers (paper list)                    ¥1.50
  ├── Scholar patents (patent list)                  ¥1.50
  └── Scholar projects (funding info)                ¥1.50

---

ワークフロー2：論文の詳細調査（約¥0.12）

ユースケース：タイトルまたはキーワードから、論文の全情報と引用チェーンを取得します。

呼び出しチェーン：

Paper search / Paper search pro (title/keyword → paper_id)
    ↓
Paper details (abstract/authors/DOI/journal/year/keywords/n_citation)  ¥0.01
    ↓
Paper citations (cited papers → cited_ids)                             ¥0.10
    ↓
(Optional) Batch paper_info for cited papers                           Free

paper_search で見つからない場合は、クエリを言い換えて再検索してください。同じテキストを paper_search_pro に送っても、結果は増えません。

---

ワークフロー3：組織分析（約¥0.81）

ユースケース：競合調査や提携評価のため、機関に所属する研究者数、論文発表数、特許数を調べます。

呼び出しチェーン：

Org disambiguation pro (raw string → org_id)  ¥0.05
    ↓
Parallel calls:
  ├── Org details (description/type)             ¥0.01
  ├── Org scholars (scholar list, 10/call)       ¥0.50
  ├── Org papers (paper list, 10/call)           ¥0.10
  └── Org patents (patent IDs, 100 per page)     ¥0.10

disambiguation pro で ID が返されない場合は、org_search（無料）にフォールバックします。

---

ワークフロー4：学術誌の論文（約¥0.10～¥0.30）

ユースケース：学術誌の論文を年ごとに追跡します。投稿先の調査やトレンド分析に役立ちます。

呼び出しチェーン：

Venue search (name → venue_id)                          Free
    ↓
(Optional) Venue details (ISSN/type/abbreviation)       ¥0.20
    ↓
Venue papers (venue_id + year → paper_id list)          ¥0.10
    ↓
(Optional) Batch paper detail query

---

ワークフロー5：特許分析（約¥0.02）

ユースケース：技術分野の特許を検索するか、研究者／機関の特許ポートフォリオを取得します。

呼び出しチェーン（単独検索）：

Patent search (query → patent_id)        Free
    ↓
Patent info / Patent details             Free / ¥0.01

呼び出しチェーン（研究者／機関経由）：

Scholar search → Scholar patents (patent_id list)
Org disambiguation → Org patents (patent_id list)
    ↓
Patent info / Patent details

---

ワークフロー6：実験情報の取得（約¥0.10）

ユースケース：ユーザーが指定した paper_id ／ method ／ dataset_name ／ search_text を使って、Experiment JSON を明示的に取得します。 費用に関する注意：experiment_search は1回あたり¥0.10です。--dry-run では experiment_search のみをプレビューします。

呼び出しチェーン：

Experiment search (paper_id / method / dataset_name / search_text)

POST は1回のみで、論文タイトルの解決は行いません。{ "results": [...] }（または構造化された API エラー）を返します。ページ数には上限があります（通常は10件以下）。このワークフローを論文の詳細調査に追加しないでください。生の JSON を要約したり、欠落しているフィールドを作り出したりしないでください。

---

個別 API クイックリファレンス

パラメーターの完全なドキュメントについては、references/api-catalog.md をご覧ください。

#	タイトル	メソッド	料金	API パス（ベース：datacenter.aminer.cn/gateway/open_platform）
1	論文 QA 検索 Pro	POST	¥0.30	/api/paper/qa/searchPro
2	論文 QA 検索（レガシー）	POST	¥0.05	/api/paper/qa/search
3	研究者検索	POST	無料	/api/person/search
4	論文検索	GET	無料	/api/paper/search
5	論文検索 Pro	GET	¥0.01	/api/paper/search/pro
6	特許検索	POST	無料	/api/patent/search
7	組織検索	POST	無料	/api/organization/search
8	会場検索	POST	無料	/api/venue/search
9	研究者の詳細	GET	¥1.00	/api/person/detail
10	研究者のプロジェクト	GET	¥1.50	/api/project/person/v3/open
11	研究者の論文	GET	¥1.50	/api/person/paper/relation
12	研究者の特許	GET	¥1.50	/api/person/patent/relation
13	研究者のプロフィール	GET	¥0.50	/api/person/figure
14	論文情報	POST	無料	/api/paper/info
15	論文の詳細（ID 100 件以下）	POST	¥0.01/返却された論文	/api/paper/detail/batch
16	論文の引用	GET	¥0.10	/api/paper/relation
17	特許情報	GET	無料	/api/patent/info
18	特許の詳細	GET	¥0.01	/api/patent/detail
19	組織の詳細	POST	¥0.01	/api/organization/detail
20	組織の特許	GET	¥0.10	/api/organization/patent/relation
21	組織の研究者	GET	¥0.50	/api/organization/person/relation
22	組織の論文	GET	¥0.10	/api/organization/paper/relation
23	会場の詳細	POST	¥0.20	/api/venue/detail
24	会場の論文	POST	¥0.10	/api/venue/paper/relation
25	組織の曖昧性解消	POST	¥0.01	/api/organization/na
26	組織の曖昧性解消 Pro	POST	¥0.05	/api/organization/na/pro
27	論文の一括クエリ	GET	¥0.10	/api/paper/list/citation/by/keywords
28	年＋会場別の論文詳細	GET	¥0.20	/api/paper/platform/allpubs/more/detail/by/ts/org/venue
29	実験検索	POST	¥0.10	/api/v3/paper/search/experiment_data/SearchPro
30	研究者の統計	POST	¥0.50	/api/person/stat

---

参考資料

• API パラメーターの完全なドキュメント：references/api-catalog.md をご覧ください。
• オプションの Python クライアント：scripts/aminer_client.py
• テストケース：evals/evals.json
• 公式ドキュメント：https://open.aminer.cn/open/docs
• コンソール：https://open.aminer.cn/open/board?tab=control