搜索 - AnyCrawl Docs

搜索引擎结果页（SERP）API，用于查询搜索引擎并获取结构化结果。

简介

AnyCrawl 搜索 API 允许你以编程方式从多个搜索引擎获取搜索结果。它专为大语言模型（LLM）构建，返回干净的结构化数据，经过 AI 处理和分析优化。

该 API 即时同步返回数据——无需轮询或 Webhook。它支持多个搜索引擎和多页结果检索，可满足全面的数据收集需求。

核心功能

多引擎支持：目前支持 Google 搜索，计划支持更多引擎
面向 LLM 优化：返回非常适合 AI 处理的结构化 JSON 数据
多语言支持：支持不同语言和地区的搜索
多页结果：在单次请求中检索多页搜索结果
高性能：原生高并发支持，配合异步处理
即时响应：同步 API——无需轮询即可立即获得结果
全面的结果：同时返回搜索结果和搜索建议

API 端点

POST https://api.anycrawl.dev/v1/search

使用示例

基础搜索（默认 Google 引擎）

curl -X POST "https://api.anycrawl.dev/v1/search" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type": "application/json" \
  -d '{
    "query": "OpenAI ChatGPT"
  }'

多页搜索

curl -X POST "https://api.anycrawl.dev/v1/search" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type": "application/json" \
  -d '{
    "query": "machine learning tutorials",
    "pages": 3,
    "limit": 10
  }'

指定语言/地区搜索

curl -X POST "https://api.anycrawl.dev/v1/search" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type": "application/json" \
  -d '{
    "query": "AnyCrawl",
    "lang": "zh",
    "pages": 2
  }'

分页搜索

curl -X POST "https://api.anycrawl.dev/v1/search" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type": "application/json" \
  -d '{
    "query": "web scraping tools",
    "offset": 20,
    "limit": 10
  }'

安全搜索

curl -X POST "https://api.anycrawl.dev/v1/search" \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type": "application/json" \
  -d '{
    "query": "educational content",
    "safe_search": 0
  }'

请求参数

参数	类型	必填	默认值	描述
`query`	string	是	-	要执行的搜索查询字符串
`template_id`	string	否	-	用于本次搜索的模板 ID
`variables`	object	否	-	模板变量（仅在提供 `template_id` 时使用）
`engine`	enum	否	`google`	使用的搜索引擎。目前支持：`google`
`limit`	number	否	10	每页最大结果数
`offset`	number	否	0	跳过的结果数量（用于分页）
`pages`	number	否	1	要检索的搜索结果页数（最小：1，最大：20）
`lang`	string	否	`en`	搜索结果的语言区域设置（例如 'en'、'zh'、'es'、'fr'）
`country`	string	否	-	搜索结果的国家/地区设置（例如 'US'、'GB'、'CN'）
`timeRange`	enum	否	-	时间范围过滤器：`day`、`week`、`month`、`year`
`sources`	enum	否	-	搜索来源：`web`、`images`、`news`（SearXNG）
`safe_search`	number \| null	否	null	Google 安全搜索过滤级别：`0`（关闭）、`1`（中等）、`2`（严格），或 null（默认）。仅适用于 Google 搜索引擎。

可选：用于结果 URL 的 `scrape_options`

提供后，每个搜索结果 URL 都可使用给定选项进行抓取（字段与 /v1/scrape 相同，不含顶层 url）。注意：非浏览器抓取时会忽略仅浏览器选项。

| 字段 | 类型 | 默认值 | 说明 | | ------------------- | ------------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | engine | enum | - | 结果 URL 的抓取引擎：auto、cheerio、playwright、puppeteer | | formats | array of enum | ["markdown"] | 输出格式：markdown、html、text、screenshot、screenshot@fullPage、rawHtml、json、summary、links | | timeout | number | 60000 | 单次请求超时时间（毫秒） | | wait_for | number | - | 提取前的延迟时间（毫秒）；仅限浏览器引擎；优先级低于 wait_for_selector | | wait_until | enum | - | 浏览器引擎的导航等待条件：load、domcontentloaded、networkidle、commit | | wait_for_selector | string, object, or array | - | 等待一个或多个选择器（仅限浏览器引擎）。接受 CSS 选择器字符串、对象 { selector: string, state?: "attached" | "visible" | "hidden" | "detached", timeout?: number } 或混合字符串/对象的数组。每个条目按顺序等待。优先级高于 wait_for。 | | include_tags | array of string | - | 仅包含匹配 CSS 选择器的元素 | | exclude_tags | array of string | - | 排除匹配 CSS 选择器的元素 | | only_main_content | boolean | true | 仅提取主要内容，移除页眉、页脚、导航等（include_tags 优先级更高） | | proxy | string (URI) | - | 可选的代理 URL | | json_options | object | - | 结构化 JSON 提取选项（schema、user_prompt、schema_name、schema_description） | | extract_source | enum | markdown | JSON 提取的来源：markdown（默认）或 html | | ocr_options | boolean | false | 启用仅针对 Markdown 图片的 OCR 增强。影响 Markdown 生成，不影响 html/rawHtml。 | | max_age | number | - | 缓存最大有效期（毫秒）。使用 0 跳过缓存读取；省略则使用服务器默认值 | | store_in_cache | boolean | true | 是否为每个结果的抓取写入页面缓存 |

支持的搜索引擎

`google`（默认）

适用场景：通用网络搜索，获取全面的结果
优势：最全面的搜索结果，支持多语言和多地区
功能：同时返回搜索结果和搜索建议。支持安全搜索过滤（关闭/中等/严格）
推荐用于：通用网络搜索、研究、内容发现
安全搜索：支持 safe_search 参数，值为 0（关闭）、1（中等）、2（严格）或 null（默认）

{
    "success": true,
    "data": [
        {
            "title": "AlsoAsked: People Also Ask keyword research tool",
            "url": "https://alsoasked.com/",
            "description": "Find the questions people also ask. Enter a question, brand or search query. e.g. 'keyword research'.",
            "source": "Google Search Result"
        },
        {
            "title": "OpenAI ChatGPT Features and Benefits",
            "url": "https://openai.com/chatgpt",
            "description": "ChatGPT is an AI assistant that can help with writing, research, and problem-solving.",
            "source": "Google Search Result"
        },
        {
            "title": "Keyword tool",
            "source": "Google Suggestions"
        }
    ]
}

搜索结果类型

API 返回两种类型的结果：

搜索结果：包含标题、URL、描述和来源的完整结果
搜索建议：搜索引擎提供的相关查询建议

错误响应

400 - 验证错误

{
    "success": false,
    "error": "Validation error",
    "details": {
        "issues": [
            {
                "field": "engine",
                "message": "Invalid enum value. Expected 'google', received 'invalid'",
                "code": "invalid_enum_value"
            }
        ],
        "messages": ["Invalid enum value. Expected 'google', received 'invalid'"]
    }
}

401 - 认证错误

{
    "success": false,
    "error": "Invalid API key"
}

402 - 需要付费

{
    "success": false,
    "error": "Insufficient credits. Please upgrade your plan or purchase more credits."
}

最佳实践

搜索引擎选择指南

通用网络搜索 → 使用 google（目前唯一支持的引擎）
多语言搜索 → 指定合适的 lang 参数
全面研究 → 使用多页获取更多结果

性能优化

批量请求：使用 pages 参数在单次请求中获取多页，而非发起多次单独请求
语言定向：指定语言以获取特定地区和本地化结果
查询优化：使用具体的关键词和短语以提升结果质量

错误处理

try {
    const response = await fetch("/v1/search", {
        method: "POST",
        headers: {
            Authorization: "Bearer YOUR_API_KEY",
            "Content-Type": "application/json",
        },
        body: JSON.stringify({
            query: "artificial intelligence",
            pages: 2,
        }),
    });

    const result = await response.json();

    if (result.success) {
        // Handle successful result
        console.log("Found results:", result.data.length);

        // Separate search results from suggestions
        const searchResults = result.data.filter((item) => item.url);
        const suggestions = result.data.filter((item) => !item.url);

        console.log("Search Results:", searchResults.length);
        console.log("Suggestions:", suggestions.length);
    } else {
        // Handle search failure
        console.error("Search failed:", result.error);
    }
} catch (error) {
    // Handle network error
    console.error("Request failed:", error);
}

高并发使用

该 API 原生支持高并发。你可以同时发起多个搜索请求，无需担心速率限制：

// Concurrent searching example
const queries = ["machine learning", "artificial intelligence", "data science"];

const searchPromises = queries.map((query) =>
    fetch("/v1/search", {
        method: "POST",
        headers: {
            Authorization: "Bearer YOUR_API_KEY",
            "Content-Type": "application/json",
        },
        body: JSON.stringify({ query, engine: "google", pages: 2 }),
    }).then((res) => res.json())
);

// All requests execute concurrently and return immediately
const results = await Promise.all(searchPromises);
console.log(`Completed ${results.length} searches simultaneously`);