Aminer Academic Search

AMiner Open Platform Academic Data Query

29 APIs + 6 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.
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 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.
4. Route by query shape, not by habit. See "Paper Search API Selection Guide". A phrase starts at free paper_search; bulk goes to paper_search_pro with size. Before spending ¥0.30 on paper_qa_search_pro you must be able to name one of four reasons — sentence, range filter, boolean exclusion, or precision-first — and if you cannot, drop down. Never send a sentence to paper_search_pro: it returns 0 and still bills.

Paper Search API Selection Guide

When the user says "search for papers", do not guess at intent. Look at two directly observable facts: is the query string a phrase or a sentence, and how many results are needed.

Two decision rules

1. Is the query a sentence (has a predicate or a question word)? Yes → only paper_qa_search_pro / paper_qa_search can parse it; the other two return 0, and paper_search_pro bills you for that 0. No → start from free paper_search and escalate only if it falls short.
2. Do you need more than 10 results? Yes → do not use paper_qa_search_pro; use paper_search_pro with size (≤100).

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×.

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 to paper_search_pro.

1. Sentence — the query is a natural-language sentence or question, so the literal-matching endpoints would return 0.
2. Range filter — you need year_from/year_to or min_citations/max_citations. The other endpoints can only enumerate exact years; they cannot express a range.
3. Boolean exclusion — you need all_terms / any_terms / exclude_terms.
4. Precision first — the user explicitly wants accurate or best-matching results, or a cheaper endpoint already came back off-topic. This is the highest-quality retrieval of the four; go straight to it rather than burning attempts to save ¥0.29. Legacy paper_qa_search also parses a sentence, but it drifts toward the dominant term: measured on how do LLM agents implement long-term memory, Pro returned 4/4 results specifically about agent long-term memory, while legacy returned 1/5 — the rest were generic "LLM-based agents" surveys.

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, authors.name/name_zh, n_citation_bucket, venue_name, year. Use paper_detail when full abstract/keywords are needed.
• Always append https://www.aminer.cn/pub/{paper_id}.

Legacy paper_qa_search — what only it can do:

• 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. Pro's cursor cannot match that (10 per page × ¥0.30).
• 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.
• Response now also carries first_author, venue_name, 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: 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

All three paper-search endpoints (paper_search, paper_search_pro, paper_qa_search) now return the same screening set — first_author, venue_name, year, n_citation_bucket — and paper_qa_search_pro returns authors, venue_name, year, n_citation_bucket. Filter on these before calling paper_detail (¥0.01 each); only fetch details for papers you will actually cite. n_citation_bucket is a coarse tier, never an exact count — do not compare buckets numerically or claim a precise citation figure from one.

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

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

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