検索 - AnyCrawl Docs

はじめに

AnyCrawl の Search API は、複数の検索エンジンの結果にプログラムからアクセスできます。大規模言語モデル（LLM）向けに設計され、AI の処理・分析に適したクリーンな構造化データを返します。

API はすぐに同期的に結果を返します。ポーリングや Webhook は不要です。複数の検索エンジンと複数ページの結果取得に対応し、幅広いデータ収集が可能です。

主な機能

マルチエンジン：現状 Google に対応。他エンジンも予定
LLM 向け：AI 処理に適した構造化 JSON
多言語：言語・地域を指定して検索可能
複数ページ：1 リクエストで複数ページの結果を取得
高パフォーマンス：ネイティブな高同時実行と非同期処理
即時応答：同期 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	1 ページあたりの最大件数
`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 | 1 リクエストあたりのタイムアウト（ミリ秒） | | wait_for | number | - | 抽出前の待機（ミリ秒）。ブラウザエンジンのみ。wait_for_selector より優先度が低い | | wait_until | enum | - | ブラウザのナビゲーション待機条件: load、domcontentloaded、networkidle、commit | | wait_for_selector | string, object, or array | - | 1 つまたは複数のセレクタを待つ（ブラウジングエンジンのみ）。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`（既定）

用途: 網羅的な結果が得られる一般的な Web 検索
利点: 最も網羅的な結果。多言語・多地域に対応
機能: 検索結果とサジェストの両方を返す。セーフサーチ（オフ／中／高）に対応
向いている用途: 一般的な Web 検索、調査、コンテンツ探索
セーフサーチ: 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 は次の 2 種類を返します。

検索結果: タイトル、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."
}

ベストプラクティス

検索エンジンの選び方

一般的な Web 検索 → google を使う（現時点で唯一対応）
多言語検索 → 適切な lang を指定する
幅広い調査 → pages を増やしてより多くの結果を取得する

パフォーマンス

バッチ: 複数回呼ぶ代わりに pages で 1 リクエストにまとめる
言語指定: 地域に合わせた言語でローカライズ結果を得やすくする
クエリ: 具体的なキーワード・フレーズで品質を上げる

エラー処理

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) {
        // 成功時の処理
        console.log("Found results:", result.data.length);

        // 検索結果とサジェストを分ける
        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 {
        // 検索失敗
        console.error("Search failed:", result.error);
    }
} catch (error) {
    // ネットワークエラー
    console.error("Request failed:", error);
}

高同時実行の使い方

API はネイティブに高同時実行に対応しています。レート制限を気にせず、複数の検索リクエストを同時に送れます。

// 同時検索の例
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())
);

// すべて同時実行され、すぐに返る
const results = await Promise.all(searchPromises);
console.log(`Completed ${results.length} searches simultaneously`);