身份验证Authentication

所有 /v1 路由都要求在 X-API-Key 请求头中携带 API 密钥。 不支持把密钥放在查询字符串里：携带 api_key 查询参数的请求会直接返回 400，无论其取值。

Every /v1 route requires an API key sent in the X-API-Key request header. Keys in the query string are rejected: a request carrying an api_key query parameter fails with 400 regardless of its value.

curl -H "X-API-Key: $SCAT_API_KEY" \
  "https://scrapingcat.boyinzhiheng.com/v1/search?engine=google_scholar&q=deep+learning"

• 密钥缺失或无效 → 401 unauthorized。
• /health 与 /ready 不需要密钥。
• 部分密钥是档案专用密钥：可获取任意作者的档案摘要与完整著作列表—— 即 /v1/profiles/{author_id}、/author（含 all_pages=true）以及 /v1/search 的 engine=google_scholar_author；访问其他任何路由都会返回 401。

• Missing or invalid key → 401 unauthorized.
• /health and /ready need no key.
• Some keys are profile-scoped: they can fetch any author's profile summary and full publication list — that is /v1/profiles/{author_id}, /author (including all_pages=true), and /v1/search with engine=google_scholar_author — and receive 401 everywhere else.

通用查询规则：参数不允许重复，未知参数会被拒绝； 如提供 output，其值必须为 json。

General query rules: keys may not be duplicated, unknown keys are rejected, and output (when supplied) must be json.

错误与状态码Errors & status codes

所有错误响应使用同一结构。request_id 对每个请求唯一——反馈问题时请附上它。

Every error response uses one fixed shape. request_id is unique per request — include it when reporting a problem.

{
  "error": {
    "code": "rate_limited",
    "message": "Request rate limit exceeded",
    "retryable": true
  },
  "request_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

GET /v1/search

一个搜索接口，六种引擎。engine 参数选择目标，并决定其余参数的取值范围。

One search endpoint, six engines. The engine parameter selects the target and determines which other parameters are valid.

engine=google 与 and engine=baidu — 网页搜索 — web search

这两个引擎仅供内部低频使用。均要求 q（1–2048 字符），接受 num 1–20（默认 10）、start ≥ 0（默认 0）、 no_cache=true|false（默认 false）以及 output=json。 Google 另接受 hl（默认 en）与可选的两位 gl； Baidu 拒绝这两个参数。Baidu 结果保留跳转链接，不做重定向解析。

These engines are for internal low-volume use. Both require q (1–2048 characters), accept num from 1–20 (default 10), start at 0 or greater (default 0), no_cache=true|false (default false), and output=json. Google also accepts hl (default en) and an optional two-letter gl; Baidu rejects both. Baidu results preserve redirect links and perform no Baidu redirect resolution.

不执行 JS/浏览器渲染。目标未启用时，这些调用可能返回 503 feature_disabled。

No JS/browser rendering is performed. These calls may return 503 feature_disabled when their target is not enabled.

engine=google_scholar — 文献搜索 — organic search

至少提供 q、cites、cluster 之一。 cluster 与 q/cites 互斥。

Requires at least one of q, cites, or cluster. cluster is exclusive with q and cites.

curl -H "X-API-Key: $SCAT_API_KEY" \
  "https://scrapingcat.boyinzhiheng.com/v1/search?engine=google_scholar&q=attention+is+all+you+need&num=10"

响应结构与 SerpApi 的 Google Scholar 形状一致： search_metadata、search_parameters、search_information、 organic_results[]（含 result_id、title、link、 publication_info、inline_links.cited_by 等），有更多页时附 pagination。

The response mirrors the SerpApi Google Scholar shape: search_metadata, search_parameters, search_information, organic_results[] (with result_id, title, link, publication_info, inline_links.cited_by, …) and pagination when more pages exist.

engine=google_scholar_author — 作者主页 — author profile

curl -H "X-API-Key: $SCAT_API_KEY" \
  "https://scrapingcat.boyinzhiheng.com/v1/search?engine=google_scholar_author&author_id=qc6CJjYAAAAJ&num=100"

需要一次取回全部著作时，可使用同语义的 /author 路由并传 all_pages=true（自动翻页直到收齐）。

To collect every publication in one call, use the equivalent /author route with all_pages=true (follows pagination until complete).

engine=google_scholar_cite — 引用导出 — citation export

q 为文献搜索响应中的 result_id。返回各引用格式 （MLA、APA、Chicago、Harvard、Vancouver）与导出链接（BibTeX、EndNote、RefMan、RefWorks）。

q is a result_id taken from an organic search response. Returns the formatted citation styles (MLA, APA, Chicago, Harvard, Vancouver) and export links (BibTeX, EndNote, RefMan, RefWorks).

curl -H "X-API-Key: $SCAT_API_KEY" \
  "https://scrapingcat.boyinzhiheng.com/v1/search?engine=google_scholar_cite&q=KlAl5vgvd-8J"

engine=google_scholar_profiles — 学者搜索 — profile search

通过 mauthors 按姓名搜索学者档案。分页使用不透明的续页令牌： 从上一次响应中取 after_author 或 before_author（二者互斥）传入。 该接口为尽力而为，高负载下可能返回可重试的上游错误。

Searches author profiles by name via mauthors. Pagination uses opaque continuation tokens: pass either after_author or before_author (mutually exclusive) from a previous response. This surface is best-effort and may return a retryable upstream error under load.

curl -H "X-API-Key: $SCAT_API_KEY" \
  "https://scrapingcat.boyinzhiheng.com/v1/search?engine=google_scholar_profiles&mauthors=Geoffrey+Hinton"

GET /v1/profiles/{author_id}

作者档案摘要：任意 Google Scholar 作者均可查询，返回一条扁平化摘要—— 姓名、机构、邮箱域名、研究方向、引用指标（总量与近五年）、高被引论文前 10 条、合作者等。 服务端维护一个持续增长的摘要缓存，仅用于加速与节省上游流量，不限定可查询的作者范围： 缓存记录在新鲜期内（默认 30 天）时即时返回且不访问上游；记录缺失或过期时， 服务会实时抓取作者首页、重建摘要、写回缓存后返回。实时刷新失败而旧记录存在时， 返回旧记录并标记 profile_cache.stale=true。

Author profile summary: look up any Google Scholar author and get one flattened record — name, affiliation, email domain, interests, citation metrics (total and recent), top-10 papers, and co-authors. The server keeps a growing summary cache purely for speed and upstream-cost savings; it does not limit which authors can be queried. A cached record within the freshness window (default 30 days) returns instantly with no upstream traffic; a missing or stale record triggers one live first-page fetch, is re-summarized, written back, and returned. If the live refresh fails while a stale record exists, the stale record is returned with profile_cache.stale=true.

curl -H "X-API-Key: $SCAT_API_KEY" \
  "https://scrapingcat.boyinzhiheng.com/v1/profiles/JicYPdAAAAAJ"

{
  "author_id": "JicYPdAAAAAJ",
  "name": "Geoffrey Hinton",
  "candidate_name": "G Hinton",
  "affiliation": "Emeritus Prof. Computer Science, University of Toronto",
  "email_domain": "cs.toronto.edu",
  "interests": [{"title": "machine learning", "link": "..."}],
  "total_citations": 1064313,
  "h_index": 129, "i10_index": 383,
  "citations_recent": 601672, "h_index_recent": 67, "i10_index_recent": 205,
  "top10_paper_titles": [{"title": "...", "year": "2012", "citations": 198341}],
  "coauthors": [{"name": "...", "author_id": "...", "affiliation": "..."}],
  "fetched_at": "2026-07-17T07:32:16+00:00",
  "profile_url": "https://scholar.google.com/citations?user=JicYPdAAAAAJ",
  "profile_cache": {"hit": true, "stale": false, "fetched_at": "..."}
}

GET /v1/fetch

抓取单个匿名公共 HTTP(S) GET 资源，仅供内部低频使用。必填 url，可选 format（html、meta、both、text、 markdown 之一；默认 markdown）、max_chars （1–1,000,000；默认 100,000）、start_index（默认 0）、 no_cache（默认 false）与 output=json。

Fetches one anonymous public HTTP(S) GET resource for internal low-volume use. Required url is accompanied by format (one of html, meta, both, text, or markdown; default markdown), max_chars (1–1,000,000; default 100,000), start_index (default 0), no_cache (default false), and output=json.

仅接受公共端口 80 与 443。每一跳重定向都会重新校验，最多 10 次。接受的 MIME 类型仅为 text/html、application/xhtml+xml 与 text/plain； 响应体上限 5,000,000 字节，请求超时 35 秒。目标返回普通 4xx/5xx 时 API 调用本身仍视为成功， 体现在 page.status_code 中。

Only public ports 80 and 443 are accepted. Redirects are revalidated at every hop, with at most 10 redirects. Accepted MIME types are exactly text/html, application/xhtml+xml, and text/plain; the body cap is 5,000,000 bytes and the request timeout is 35 seconds. Ordinary target 4xx/5xx responses remain successful API responses and are represented in page.status_code.

不支持 JS/浏览器渲染、登录、会话、自定义请求头、Cookie、POST、请求体、批量或爬取。 响应使用标准的 fetch_metadata、fetch_parameters 与 page 对象；错误使用标准 error + request_id 结构，目标关闭时返回 503 feature_disabled。

No JS/browser rendering, no login, no session, no caller headers, no cookies, no POST, no body, no batch, and no crawl are supported. The response uses the standard fetch_metadata, fetch_parameters, and page objects; errors use the standard error plus request_id shape, including 503 feature_disabled when the target is off.

GET /v1/papers/resolve

面向 Google Scholar 的确定性论文解析。提供恰好一个选择器：

Deterministic paper lookup against Google Scholar. Supply exactly one selector:

curl -H "X-API-Key: $SCAT_API_KEY" \
  "https://scrapingcat.boyinzhiheng.com/v1/papers/resolve?doi=10.1038/nature14539"

响应给出显式的 match_status——exact、probable、 ambiguous 或 not_found——以及匹配到的结果（标识符、标题、链接、引用数） 与参与比对的候选，便于调用方套用自己的接受策略。

The response reports an explicit match_status — exact, probable, ambiguous, or not_found — together with the matched result (identifiers, title, link, citation counts) and the candidates that were considered, so callers can apply their own acceptance policy.

持久化批量任务Durable batches

批量任务异步处理成千上万个作者或论文，状态持久化：任务元数据、逐条进度、重试、 暂停/恢复、崩溃安全的结果归档都能在服务重启后存活。提交输入、轮询状态， 然后下载压缩的 NDJSON 归档——每个规范化输入对应一条终态记录。

Batches process thousands of authors or papers asynchronously with durable state: batch metadata, per-item progress, retries, pause/resume, and crash-safe result archives all survive service restarts. Submit inputs, poll status, then download a compressed NDJSON archive of one terminal record per canonical input.

• 作者输入携带 author_id；论文输入携带 doi、pmid、arxiv_id、title 中的恰好一个。
• 重复输入会被规范化去重，保留首次出现的序号。
• 可选的 Idempotency-Key 请求头让创建可安全重放：相同键 + 相同规范内容返回原任务； 相同键 + 不同内容返回 409。

• Author inputs carry author_id. Paper inputs carry exactly one of doi, pmid, arxiv_id, or title.
• Duplicate inputs are canonicalized; the first occurrence's index is retained.
• An optional Idempotency-Key header makes creation replay-safe: the same key with identical canonical content returns the original batch; the same key with different content returns 409.

批量任务接口Batch endpoints

curl -X POST -H "X-API-Key: $SCAT_API_KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: my-batch-2026-07-17" \
  -d '{"items":[{"author_id":"qc6CJjYAAAAJ"},{"author_id":"JicYPdAAAAAJ"}],"options":{"hl":"en"}}' \
  "https://scrapingcat.boyinzhiheng.com/v1/batches/authors"

curl -H "X-API-Key: $SCAT_API_KEY" \
  -o results.ndjson.gz \
  "https://scrapingcat.boyinzhiheng.com/v1/batches/b_01J.../results.ndjson.gz"

归档中每一行是一条 JSON 记录：条目的原始 input_index、规范化输入、终态，以及完整结果文档或固定的错误分类。

Each archive line is one JSON record with the item's original input_index, canonical input, terminal state, and either the full result document or a fixed error classification.

批量与条目状态Batch & item states

ingesting → queued → running → completed | completed_with_errors | failed
                       │
                       └→ pausing → paused → queued  (on resume)

条目状态：pending、running、retry_wait、 succeeded、not_found、failed。对象不存在 （如未知的 author_id）终态为 not_found，而非 failed。

Item states: pending, running, retry_wait, succeeded, not_found, failed. A missing entity (e.g. an unknown author_id) terminates as not_found, not failed.

限额与保留期Limits & retention

健康与就绪检查Health & readiness