aminer-academic-search

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

29 個の 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、N 回の API 呼び出し（api_a：¥X.XX × N、api_b：無料 × N）。
7. 高額な呼び出しの確認（≥ ¥5）：見積もり合計コストが ¥5.00 以上のワークフローまたは一連の呼び出しを実行する前に、必ず停止してユーザーに確認してください。予定している呼び出しの流れ、各ステップの見積もりコスト、合計を提示してください。ユーザーが明示的に同意してから実行してください。これは、定義済みのワークフロー（例：研究者プロフィール約 ¥6.00）と、その場で組み立てる複数ステップのプランの両方に適用されます。
8. 実験データの意図確認：experiment_search を呼び出すのは、ユーザーが実験レベルのデータ、Experiment JSON、手法、データセット、または構造化された実験結果を明示的に要求した場合に限ります。通常の論文検索、要旨／引用の照会、研究者／組織／学術誌／特許のリクエスト、広範なトピック検索、デフォルトの論文詳細調査ワークフローには、決して追加しないでください。

エンティティ 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 はバッチ専用です：{"ids": [...]}。paper_detail は単一論文専用で、id を 1 つ指定します。両者を混在させないでください。
3. 複数の詳細情報が必要な場合は、まず低コストの API で絞り込んでから、少数の対象について詳細を取得してください。
4. 慣例ではなく、クエリの形状に応じて使い分けてください。「論文検索 API 選択ガイド」を参照してください。語句検索は無料の paper_search から始め、バルク検索には size を指定した paper_search_pro を使用します。paper_qa_search_pro に ¥0.30 を費やす前に、4 つの理由のいずれか（文、範囲フィルター、ブール式による除外、精度優先）を明確に挙げられる必要があります。挙げられない場合は、より低コストの API を選んでください。paper_search_pro に文を送らないでください。結果は 0 件でも課金されます。

論文検索 API の選択ガイド

ユーザーが「論文を検索して」と言ったときは、意図を推測しないでください。直接確認できる次の 2 つの事実に注目します。クエリ文字列が句か文か、そして必要な結果の件数です。

API	対応する入力	この API でのみ可能なこと	制限事項	費用
paper_search	句	無料です	title フィールドのみ。size ≤ 20。フィルターとソートはありません	無料
paper_search_pro	句。フィールド単位（title/keyword/abstract/author/org/venue）	1 ページあたり 100 件＋確実なソート（order=year|n_citation）。大量検索で最安	文を指定すると 0 件になり、その場合も課金されます	¥0.01
paper_qa_search	句または文	重み付けされたネスト型 AND/OR（topic_high/middle/low）、sci_flag、最大 10000 件までの offset	年や被引用数の範囲指定、ブール値による除外はできません	¥0.05
paper_qa_search_pro	文、口語表現または中国語の質問	意味解析＋年／被引用数の範囲指定＋all/any/exclude によるブール条件＋sort モード。検索精度が最良	1 ページあたり固定で 10 件。以降のページごとにさらに ¥0.30 かかります	¥0.30
paper_list_by_keywords	複数のキーワード	テーマごとの一括検索	—	¥0.10
paper_detail_by_condition	年＋掲載先	詳細を直接返します	—	¥0.20

2 つの判断ルール

1. クエリは文ですか（述語または疑問詞を含みますか）？ はい → 解析できるのは paper_qa_search_pro / paper_qa_search だけです。他の 2 つは 0 件を返し、paper_search_pro はその 0 件にも課金されます。いいえ → 無料の paper_search から始め、結果が不十分な場合にのみ上位 API に切り替えます。
2. 10 件を超える結果が必要ですか？ はい → paper_qa_search_pro は使わないでください。size（≤100）を指定して paper_search_pro を使います。

費用の差は必ず覚えておいてください。 100 件の場合、paper_search_pro で size=100 を指定すれば 1 回の呼び出しで ¥0.01 です。paper_qa_search_pro ではカーソルを使って 10 ページ取得するため、¥3.00 かかります。300 倍です。

¥0.30 を使うための厳格なルール

paper_qa_search_pro を呼び出す前に、次の理由のうち少なくとも 1 つを挙げられる必要があります。挙げられない場合は、paper_search_pro に切り替えてください。

1. 文 — クエリが自然言語の文または質問であるため、文字列照合を行うエンドポイントでは 0 件になります。
2. 範囲フィルター — year_from/year_to または min_citations/max_citations が必要です。他のエンドポイントでは年を個別に指定して列挙することしかできず、範囲を指定できません。
3. ブール値による除外 — all_terms / any_terms / exclude_terms が必要です。
4. 精度を優先 — ユーザーが正確な結果、または最も一致する結果を明示的に求めているか、より安価なエンドポイントでトピックから外れた結果が返されました。4 つの中で最も検索精度が高いため、¥0.29 を節約するために試行を重ねず、直接これを使ってください。従来の paper_qa_search も文を解析しますが、主要な語句に引きずられる傾向があります。how do LLM agents implement long-term memory で測定したところ、Pro は 4/4 件がエージェントの長期記憶を具体的に扱っていましたが、従来版は 1/5 件のみで、残りは一般的な「LLM ベースのエージェント」に関するサーベイでした。

4 つの理由のどれにも当てはまらないなら、何も得ずに 30 倍の費用を払うことになります。下位の API に切り替えてください。

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、authors.name/name_zh、n_citation_bucket、venue_name、year のみです。要約やキーワードの全文が必要な場合は 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件を取得できます。Pro のカーソルでは同じことはできません（1ページあたり10件 × 0.30円）。
• SCI 論文に絞り込む sci_flag があります。Pro にはこのフィルターがありません。
• query と topic_high/topic_middle/topic_low は相互に排他的です。両方を渡さないでください。
• レスポンスには first_author、venue_name、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つは空でない値にしてください。前後の空白を削除する以外は、フィールドを作り出さないでください。
• 生の JSON リクエストでは、Experiment オブジェクトを書き換えずに { "results": [...] } を返します。

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

• paper_search：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

3つの論文検索エンドポイント（paper_search、paper_search_pro、paper_qa_search）はすべて、同じスクリーニング用フィールドセット（first_author、venue_name、year、n_citation_bucket）を返すようになりました。paper_qa_search_pro は authors、venue_name、year、n_citation_bucket を返します。paper_detail（1件あたり0.01円）を呼び出す前に、これらのフィールドで絞り込んでください。実際に引用する論文の詳細のみを取得してください。n_citation_bucket は大まかな段階を示すもので、正確な件数ではありません。バケットを数値として比較したり、正確な被引用数を示すものとして扱ったりしないでください。

---

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

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

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

---

6つの統合ワークフロー

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

用途：研究者の完全なプロフィール — 略歴、研究関心、論文、特許、プロジェクト。 費用に関する注意：すべて実行すると5円のしきい値を超えるため、開始前に必ずユーザーの確認を求めてください（ルール7）。予定している手順と費用を提示してください。必要なサブモジュールを確認し、依頼されていない特許やプロジェクトは省略してください。

呼び出しチェーン：

Scholar search (name → person_id)
    ↓
Parallel calls (pick as needed):
  ├── Scholar details (bio/education/honors)         ¥1.00
  ├── 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

フォールバック：サブステップで paper_search の結果が得られない場合は、paper_search_pro に切り替えてください。

---

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

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

呼び出しチェーン：

Paper search / Paper search pro (title/keyword → paper_id)
    ↓
Paper details (abstract/authors/DOI/journal/year/keywords)  ¥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, up to 10,000)     ¥0.10

名寄せ 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 は呼び出しごとに ¥0.10 です。--dry-run でプレビューされるのは experiment_search のみです。

呼び出しチェーン：

Experiment search (paper_id / method / dataset_name / search_text)

単一の POST で実行され、論文タイトルの解決は行われません。{ "results": [...] }（または構造化された API エラー）が返されます。ページ数には上限があります（通常は 10 以下）。このワークフローを Paper Deep Dive に追加しないでください。生の 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	論文の詳細	GET	¥0.01	/api/paper/detail
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

---

参考資料

• 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