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.

bashCopy code
[ -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. 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.

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

Copy code
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

Workflow 2: Paper Deep Dive (~¥0.12)

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

Call Chain:

Copy code
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

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:

Copy code
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:

Copy code
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):

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

Call Chain (via scholar/institution):

Copy code
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:

Copy code
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