Aminer Open Academic Search

---
name: aminer-open-academic-search
description: "ACADEMIC PRIORITY: Activate this skill whenever the user's query involves academic, scholarly, or research-related topics — including but not limited to: papers, publications, citations, scholars, researchers, professors, institutions, universities, labs, journals, conferences,…"
category: "Community"
author: community
version: "1.1.1"
icon: puzzle
---

# AMiner Open Platform Academic Data Query

27 APIs + 5 workflows. Token required: set `AMINER_API_KEY` env var.
- Docs: https://open.aminer.cn/open/docs | Console: https://open.aminer.cn/open/board?tab=control

---

## Mandatory Rules (Critical)

1. **Token Security**: Only check whether `AMINER_API_KEY` exists; never expose the token in plain text anywhere.
2. **Cost Control**: Prefer optimal combined queries; never do indiscriminate full-detail retrieval. Default to top 10 details when the user has not specified a count.
3. **Free-First**: Prefer free APIs unless the user explicitly requires deeper fields; only upgrade to paid APIs when free ones cannot satisfy the need.
4. **Result Links**: Always append an accessible URL after each entity in the output.
5. **Disambiguation**: Scholar ambiguity → filter by `org`/`org_id` or ask user to confirm. Org ambiguity → use `org_disambiguate_pro`. Paper ambiguity → cross-check `year` + `venue_name` + `first_author`.
6. **Cost Report**: After completing all API calls, always output a cost summary to the user showing: each API called, its unit price, number of calls, and the total cost. Format example: `[Cost] ¥X.XX total, N API calls (api_a: ¥X.XX × N, api_b: Free × N)`.
7. **High-Cost Confirmation (≥ ¥5)**: Before executing a workflow or call chain whose estimated total cost is ¥5.00 or more, **stop and ask the user for confirmation** first. Show the planned call chain, estimated cost per step, and the total. Only proceed after the user explicitly agrees. This applies to both predefined workflows (e.g., Scholar Profile ~¥6.00) and ad-hoc multi-step plans.

Entity URL templates (mandatory):
- Paper: `https://www.aminer.cn/pub/{paper_id}`
- Scholar: `https://www.aminer.cn/profile/{scholar_id}`
- Patent: `https://www.aminer.cn/patent/{patent_id}`
- Journal: `https://www.aminer.cn/open/journal/detail/{journal_id}`

---

## Token Check (Required)

Check `AMINER_API_KEY` exists before any API call. Never expose token in plain text.

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

- If `${AMINER_API_KEY}` exists: proceed. If not: check `--token` parameter. If neither: **stop**, guide user to [Console](https://open.aminer.cn/open/board?tab=control) to generate one.
- If the user provides `AMINER_API_KEY` inline (e.g. "My token is xxx"), accept it for the current session, but recommend setting it as an environment variable for better security.
- Default headers: `Authorization: ${AMINER_API_KEY}`, `X-Platform: openclaw`, `Content-Type: application/json;charset=utf-8` (POST).

---

## Call Guardrails

1. Parameter names and types must match `references/api-catalog.md` exactly.
2. `paper_info` is batch-only: `{"ids": [...]}`. `paper_detail` is single-paper only: one `id`. Never mix them.
3. When multiple details are needed, filter with a low-cost API first, then fetch details for a small set.

---

## Paper Search API Selection Guide

When the user says "search for papers", determine the goal first:

| API | Focus | Use Case | Cost |
|---|---|---|---|
| `paper_search` | Title search → `paper_id` | Known paper title, locate target | Free |
| `paper_search_pro` | Multi-condition search (author/org/venue/keyword) | Topic search, sort by citations or year | ¥0.01 |
| `paper_qa_search` | Natural language Q&A / topic keyword search | Semantic search, structured keyword OR/AND | ¥0.05 |
| `paper_list_by_keywords` | Multi-keyword batch retrieval | Batch thematic retrieval | ¥0.10 |
| `paper_detail_by_condition` | Year + venue dimension | Journal annual monitoring | ¥0.20 |

Default routing:

1. **Known title**: `paper_search -> paper_detail -> paper_relation`
2. **Conditional filtering**: `paper_search_pro -> paper_detail`
3. **Natural language Q&A**: `paper_qa_search` (fall back to `paper_search_pro` if no results)
4. **Journal annual analysis**: `venue_search -> venue_paper_relation -> paper_detail_by_condition`

Key `paper_qa_search` rules:
- `query` and `topic_high/topic_middle/topic_low` are **mutually exclusive**; do not pass both.
- `query` mode: pass a natural language string. `topic_*` mode: expand synonyms/English variants first.
- Supports `sci_flag`, `force_citation_sort`, `force_year_sort`, `author_id`, `org_id`, `venue_ids` filters.

Free-tier screening fields available:

- `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`

---

## Handling Out-of-Workflow Requests

When the user's request falls outside the 5 workflows:

1. Read `references/api-catalog.md` to confirm available APIs, parameters, and response fields.
2. Design the shortest viable call chain: locate ID → supplement details → expand relationships.
3. Do not give up because "no existing workflow fits"; actively compose APIs based on `api-catalog`.

---

## 5 Combined Workflows

### Workflow 1: Scholar Profile (~¥6.00)

**Use Case**: Complete academic profile — bio, research interests, papers, patents, projects.
**Cost note**: Full execution exceeds the ¥5 threshold → **must ask for user confirmation before proceeding** (Rule 7). Show the planned steps and cost. Confirm which sub-modules are needed; skip patents/projects if not requested.

**Call Chain:**
```
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
```

Fallback: if `paper_search` yields no results in sub-steps, fall back to `paper_search_pro`.

---

### Workflow 2: Paper Deep Dive (~¥0.12)

**Use Case**: Full paper information and citation chain from a title or keyword.

**Call Chain:**
```
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
```

Fallback: if `paper_search` yields no results, fall back to `paper_search_pro`.

---

### Workflow 3: Org Analysis (~¥0.81)

**Use Case**: Institution scholar size, paper output, patent count — for competitive research or partnership evaluation.

**Call Chain:**
```
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
```

> If disambiguation pro returns no ID, fall back to `org_search` (free).

---

### Workflow 4: Venue Papers (~¥0.10 - ¥0.30)

**Use Case**: Track journal papers by year; useful for submission research or trend analysis.

**Call Chain:**
```
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
```

---

### Workflow 5: Patent Analysis (~¥0.02)

**Use Case**: Search patents in a technology domain, or retrieve a scholar's/institution's patent portfolio.

**Call Chain (standalone search):**
```
Patent search (query → patent_id)        Free
    ↓
Patent info / Patent details             Free / ¥0.01
```

**Call Chain (via scholar/institution):**
```
Scholar search → Scholar patents (patent_id list)
Org disambiguation → Org patents (patent_id list)
    ↓
Patent info / Patent details
```

---

## Individual API Quick Reference

> Full parameter docs: read `references/api-catalog.md`

| # | Title | Method | Price | API Path (Base: datacenter.aminer.cn/gateway/open_platform) |
|---|------|------|------|------|
| 1 | Paper QA Search | POST | ¥0.05 | `/api/paper/qa/search` |
| 2 | Scholar Search | POST | Free | `/api/person/search` |
| 3 | Paper Search | GET | Free | `/api/paper/search` |
| 4 | Paper Search Pro | GET | ¥0.01 | `/api/paper/search/pro` |
| 5 | Patent Search | POST | Free | `/api/patent/search` |
| 6 | Org Search | POST | Free | `/api/organization/search` |
| 7 | Venue Search | POST | Free | `/api/venue/search` |
| 8 | Scholar Details | GET | ¥1.00 | `/api/person/detail` |
| 9 | Scholar Projects | GET | ¥1.50 | `/api/project/person/v3/open` |
| 10 | Scholar Papers | GET | ¥1.50 | `/api/person/paper/relation` |
| 11 | Scholar Patents | GET | ¥1.50 | `/api/person/patent/relation` |
| 12 | Scholar Portrait | GET | ¥0.50 | `/api/person/figure` |
| 13 | Paper Info | POST | Free | `/api/paper/info` |
| 14 | Paper Details | GET | ¥0.01 | `/api/paper/detail` |
| 15 | Paper Citations | GET | ¥0.10 | `/api/paper/relation` |
| 16 | Patent Info | GET | Free | `/api/patent/info` |
| 17 | Patent Details | GET | ¥0.01 | `/api/patent/detail` |
| 18 | Org Details | POST | ¥0.01 | `/api/organization/detail` |
| 19 | Org Patents | GET | ¥0.10 | `/api/organization/patent/relation` |
| 20 | Org Scholars | GET | ¥0.50 | `/api/organization/person/relation` |
| 21 | Org Papers | GET | ¥0.10 | `/api/organization/paper/relation` |
| 22 | Venue Details | POST | ¥0.20 | `/api/venue/detail` |
| 23 | Venue Papers | POST | ¥0.10 | `/api/venue/paper/relation` |
| 24 | Org Disambiguation | POST | ¥0.01 | `/api/organization/na` |
| 25 | Org Disambiguation Pro | POST | ¥0.05 | `/api/organization/na/pro` |
| 26 | Paper Batch Query | GET | ¥0.10 | `/api/paper/list/citation/by/keywords` |
| 27 | Paper Details by Year+Venue | GET | ¥0.20 | `/api/paper/platform/allpubs/more/detail/by/ts/org/venue` |

---

## References

- Full API parameter documentation: read `references/api-catalog.md`
- Optional Python client: `scripts/aminer_client.py`
- Test cases: `evals/evals.json`
- Official documentation: https://open.aminer.cn/open/docs
- Console: https://open.aminer.cn/open/board?tab=control