搜尋 - 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`);