SuperAPI AI Directory

aminer-academic-search

Writing & research

View repository

Updated 11-11 17:16

About this skill

AMiner Open Platform Academic Data Query

30 APIs + 6 workflows. Token required: set AMINER_API_KEY env var.


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.50) and ad-hoc multi-step plans.
  8. Experiment Intent Boundary: Call experiment_search only when the user explicitly asks for experiment-level data, Experiment JSON, methods, datasets, or structured experimental results. Never add it to ordinary paper search, abstract/citation lookup, scholar/org/venue/patent requests, broad topic search, or the default Paper Deep Dive workflow.

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.

[ -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 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 (current host: claude-code / cursor / codex / openclaw; unknown if it cannot be determined), X-Skill-Name: aminer-academic-search, X-Skill-Version (this file's frontmatter version), Content-Type: application/json;charset=utf-8 (POST). Always send X-Platform and the two X-Skill-* headers.

Call Guardrails

  1. Parameter names and types must match references/api-catalog.md exactly.
  2. paper_info (free cards) and paper_detail (full details, ¥0.01 per returned paper) both take {"ids": [...]} (≤100). Fetch several papers' details in one paper_detail call instead of one call per paper.
  3. When multiple details are needed, filter with a low-cost API first, then fetch details for a small set.
  4. Climb the search ladder one rung at a time. See "Paper Search API Selection Guide". Start at free paper_search; move up only for a parameter the current tier lacks. Before spending ¥0.30 on paper_qa_search_pro you must be able to name one of four reasons — complex question, citation range, boolean exclusion, or precision-first — and if you cannot, drop down. A year window is never such a reason: paper_search and paper_search_pro both take year_from/year_to.

Paper Search API Selection Guide

The four paper-search endpoints form an upgrade ladder. Pick the lowest tier that has the parameter you need.

Tier API What it offers Hard limit Cost
1 paper_search One search box query (title + keywords); year / year_from / year_to ≤20/page, ≤10 pages; no per-field conditions, no sort Free
2 paper_search_pro Everything in tier 1, plus per-field title/keyword/abstract/author/org/venue, order=year|n_citation, ≤100/page — cheapest bulk — ¥0.01
3 paper_qa_search Keywords extracted server-side from query; weighted topic_high/middle/low; author/org/venue ID filters; doi; sci_flag; offset ≤ 10000 Exact year list only, no ranges; no boolean exclusion ¥0.05
4 paper_qa_search_pro Natural-language understanding; year and citation ranges; all/any/exclude; sort modes; full authors list; best retrieval quality Fixed 10/page; every further page costs another ¥0.30 ¥0.30
— paper_list_by_keywords Batch thematic retrieval — ¥0.10
— paper_detail_by_condition Year + venue, returns details directly — ¥0.20

Upgrade rules

  1. Start at paper_search. A phrase, a known title, or a short sentence all return results; add year_from/year_to for a time window.
  2. Need a per-field condition (author, institution, venue, abstract), a sort, or more than 20 per page? → paper_search_pro.
  3. Need an author/org/venue ID filter, a DOI, SCI only, or weighted topic tiers? → paper_qa_search.
  4. Need a complex question understood, a citation range, a boolean exclusion, or precision-first? → paper_qa_search_pro.

Cost cliff — memorise this. For 100 results: paper_search_pro with size=100 is one call at ¥0.01; paper_qa_search_pro needs 10 cursor pages = ¥3.00. 300×. Never use tier 4 for volume.

Hard rule for spending ¥0.30

Before calling paper_qa_search_pro, you must be able to name at least one of these reasons. If you cannot, drop down.

  1. Complex question — a natural-language question whose meaning a term match cannot capture (multiple concepts, relations, colloquial or Chinese phrasing), or a cheaper tier already came back off-topic for it.
  2. Citation range — you need min_citations/max_citations. (A year range is available on paper_search / paper_search_pro and is not a reason.)
  3. Boolean exclusion — you need all_terms / any_terms / exclude_terms.
  4. Precision first — the user explicitly wants accurate or best-matching results. Measured on how do LLM agents implement long-term memory, Pro returned 4/4 results specifically about agent long-term memory, while legacy paper_qa_search returned 1/5.

None of the four applies = paying 30× for nothing. Drop down.

Key paper_qa_search_pro rules:

  • Use the natural-language query field (query_type="auto", the default) and pass the user's original question as a whole sentence. Do not pre-split it into keywords and reassemble them into all_terms — splitting throws away the semantic understanding you are paying for, and precision drops below just asking. Fall back to query_type="topic" only when literal term matching is genuinely required.
  • Page size is fixed at 10. Do not send size. Paginate with next_cursor → next request body is {"cursor":"..."} only.
  • sort: relevance / balanced / recent / citation. For “most cited” use citation; for “newest” use recent.
  • Response card fields only: paper_id, title, title_zh, doi, authors.name/name_zh, n_citation_bucket, venue_name, year. Use paper_detail when full abstract/keywords or an exact citation count (n_citation) are needed.
  • Always append https://www.aminer.cn/pub/{paper_id}.

paper_qa_search key rules:

  • Weighted nested AND/OR: topic_high / topic_middle / topic_low give three boost tiers. Pro has no equivalent. Use it for "must contain A, strongly boost B, weakly boost C".
  • Deep paging: size ≤ 100 with offset ≤ 10000 — 100 results for ¥0.05, which paper_qa_search_pro's cursor cannot match (10 per page × ¥0.30). For plain volume paper_search_pro is cheaper still (¥0.01 per 100).
  • sci_flag restricts to SCI papers; Pro has no such filter.
  • query and topic_high/topic_middle/topic_low are mutually exclusive; do not pass both. query and topic_* need use_topic: true.
  • Response carries doi, first_author, venue_name, venue_id, year, n_citation_bucket — screen on those before paying for paper_detail.

Experiment retrieval selection:

  • Use experiment_search only for explicit experiment-level intent (¥0.10/call).
  • Exact filters: paper_id, method, dataset_name (→ backend dataset).
  • Free text (paper title, experiment name, problem/method/conclusion, etc.) → search_text (ES over paper_title, experiment_name, research_problem, research_problem_description, research_goal, method name/description text, conclusion, limitations, key_results).
  • Response shape: each result carries methods: [{name, description, ...}] (a list); some older records may still have flat method / method_description. Return objects as-is — read methods first, and never flatten the list into a single method string.
  • Do not call paper_search to resolve titles; do not send a separate experiment_name parameter.
  • At least one of paper_id, method, dataset_name, search_text must be non-empty. Trim-only; do not invent fields.
  • Raw JSON requests return { "results": [...] } without rewriting Experiment objects.

Free-tier screening fields available:

  • 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 and paper_qa_search return the same screening set — doi, first_author, venue_name, year, n_citation_bucket; paper_qa_search additionally returns venue_id (venue entity ID, when linked — feeds the venue APIs); paper_qa_search_pro returns the full authors list plus doi, venue_name, year, n_citation_bucket. Filter on these before calling paper_detail (¥0.01 per returned paper, IDs not found are free); only fetch details for papers you will actually cite, in one call. n_citation_bucket is a coarse tier, never an exact count — do not compare buckets numerically or claim a precise citation figure from one; paper_detail returns the exact n_citation.


Handling Out-of-Workflow Requests

When the user's request falls outside the 6 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.

6 Combined Workflows

Workflow 1: Scholar Profile (~¥6.50)

Use Case: Complete academic profile — bio, metrics, 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 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

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/n_citation)  ¥0.01
    ↓
Paper citations (cited papers → cited_ids)                             ¥0.10
    ↓
(Optional) Batch paper_info for cited papers                           Free

If paper_search finds nothing, reformulate the query and search again; sending the same text to paper_search_pro will not return more results.


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, 100 per page)     ¥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

Workflow 6: Experiment Retrieval (~¥0.10)

Use Case: Explicit Experiment JSON via user-supplied paper_id / method / dataset_name / search_text. Cost note: experiment_search is ¥0.10 per call. --dry-run previews only experiment_search.

Call Chain:

Experiment search (paper_id / method / dataset_name / search_text)

Single POST; no paper-title resolution. Returns { "results": [...] } (or a structured API error). Page-limited (commonly ≤10). Never add this workflow to Paper Deep Dive. Do not summarize raw JSON or invent missing fields.


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 Pro POST ¥0.30 /api/paper/qa/searchPro
2 Paper QA Search (legacy) POST ¥0.05 /api/paper/qa/search
3 Scholar Search POST Free /api/person/search
4 Paper Search GET Free /api/paper/search
5 Paper Search Pro GET ¥0.01 /api/paper/search/pro
6 Patent Search POST Free /api/patent/search
7 Org Search POST Free /api/organization/search
8 Venue Search POST Free /api/venue/search
9 Scholar Details GET ¥1.00 /api/person/detail
10 Scholar Projects GET ¥1.50 /api/project/person/v3/open
11 Scholar Papers GET ¥1.50 /api/person/paper/relation
12 Scholar Patents GET ¥1.50 /api/person/patent/relation
13 Scholar Portrait GET ¥0.50 /api/person/figure
14 Paper Info POST Free /api/paper/info
15 Paper Details (≤100 IDs) POST ¥0.01/returned paper /api/paper/detail/batch
16 Paper Citations GET ¥0.10 /api/paper/relation
17 Patent Info GET Free /api/patent/info
18 Patent Details GET ¥0.01 /api/patent/detail
19 Org Details POST ¥0.01 /api/organization/detail
20 Org Patents GET ¥0.10 /api/organization/patent/relation
21 Org Scholars GET ¥0.50 /api/organization/person/relation
22 Org Papers GET ¥0.10 /api/organization/paper/relation
23 Venue Details POST ¥0.20 /api/venue/detail
24 Venue Papers POST ¥0.10 /api/venue/paper/relation
25 Org Disambiguation POST ¥0.01 /api/organization/na
26 Org Disambiguation Pro POST ¥0.05 /api/organization/na/pro
27 Paper Batch Query GET ¥0.10 /api/paper/list/citation/by/keywords
28 Paper Details by Year+Venue GET ¥0.20 /api/paper/platform/allpubs/more/detail/by/ts/org/venue
29 Experiment Search POST ¥0.10 /api/v3/paper/search/experiment_data/SearchPro
30 Scholar Statistics POST ¥0.50 /api/person/stat

References