Node SDK | Evocrawl

Node.js アプリケーションから、単一ページをスクレイピングし、サイト全体をクロールし、URL をマップできます。SDK がページネーション、リトライ、非同期ジョブのポーリングを処理するため、返されたデータの利用に集中できます。

インストール

Evocrawl の Node SDK をインストールするには、npm を使用します。

Node（Node.js）

# npm install @mendable/evocrawl-js

import Evocrawl from '@mendable/evocrawl-js';

const evocrawl = new Evocrawl({ apiKey: "fc-YOUR-API-KEY" });

使い方

evocrawl.dev から API キーを取得します。
環境変数 EVOCRAWL_API_KEY に API キーを設定するか、EvocrawlApp クラスにパラメータとして渡します。

エラーハンドリング付きで SDK を使用する例は次のとおりです:

Node

import Evocrawl from '@mendable/evocrawl-js';

const evocrawl = new Evocrawl({apiKey: "fc-YOUR_API_KEY"});

// ウェブサイトをスクレイピングする
const scrapeResponse = await evocrawl.scrape('https://evocrawl.com', {
  formats: ['markdown', 'html'],
});

console.log(scrapeResponse)

// ウェブサイトをクロールする
const crawlResponse = await evocrawl.crawl('https://evocrawl.com', {
  limit: 100,
  scrapeOptions: {
    formats: ['markdown', 'html'],
  }
});

console.log(crawlResponse)

URLをスクレイピングする

エラー処理付きで単一のURLをスクレイプするには、scrapeUrl メソッドを使用します。URLを引数に取り、スクレイプしたデータをディクショナリ（辞書）として返します。

Node

// ウェブサイトをスクレイピングする：
const scrapeResult = await evocrawl.scrape('evocrawl.com', { formats: ['markdown', 'html'] });

console.log(scrapeResult)

ウェブサイトのクロール

エラーハンドリング込みでウェブサイトをクロールするには、crawlUrl メソッドを使用します。開始URLと任意のパラメータを引数に取ります。params 引数では、クロールする最大ページ数、許可ドメイン、出力フォーマットなど、クロールジョブの追加オプションを指定できます。自動／手動のページネーションや上限設定については Pagination を参照してください。

Node

const job = await evocrawl.crawl('https://docs.evocrawl.com', { limit: 5, pollInterval: 1, timeout: 120 });
console.log(job.status);

サイトマップのみクロール

sitemap: "only" を使用すると、サイトマップ内の URL のみをクロールします（開始URLは常に対象に含まれ、HTML リンクの探索は行われません）。

Node

const job = await evocrawl.crawl('https://docs.evocrawl.com', {
  sitemap: 'only',
  limit: 25,
});
console.log(job.status, job.data.length);

クローリングを開始

startCrawl を使うと待機せずにジョブを開始できます。ステータス確認に使えるジョブの ID が返されます。完了まで処理をブロックするウェイターが必要な場合は crawl を使用してください。ページングの挙動と制限については Pagination を参照してください。

Node

const { id } = await evocrawl.startCrawl('https://docs.evocrawl.com', { limit: 10 });
console.log(id);

クロールのステータス確認

エラー処理付きでクロールジョブのステータスを確認するには、checkCrawlStatus メソッドを使用します。ID を引数に取り、クロールジョブの現在のステータスを返します。

Node

const status = await evocrawl.getCrawlStatus("<crawl-id>");
console.log(status);

クロールのキャンセル

クロールジョブをキャンセルするには、cancelCrawl メソッドを使用します。startCrawl のジョブIDを引数に渡すと、キャンセル結果のステータスが返されます。

Node

const ok = await evocrawl.cancelCrawl("<crawl-id>");
console.log("キャンセル済み:", ok);

ウェブサイトのマッピング

エラー処理込みでウェブサイトをマッピングするには、mapUrl メソッドを使用します。開始 URL を引数に取り、マッピング結果をディクショナリとして返します。

Node

const res = await evocrawl.map('https://evocrawl.com', { limit: 10 });
console.log(res.links);

WebSocket を使ったサイトのクロール

WebSocket を使ってサイトをクロールするには、crawlUrlAndWatch メソッドを使用します。開始 URL と任意のパラメータを引数に取ります。params 引数では、クロールする最大ページ数、許可ドメイン、出力フォーマットなど、クロールジョブの追加オプションを指定できます。

Node

import Evocrawl from '@mendable/evocrawl-js';

const evocrawl = new Evocrawl({ apiKey: 'fc-YOUR-API-KEY' });

// クロールを開始して監視する
const { id } = await evocrawl.startCrawl('https://mendable.ai', {
  excludePaths: ['blog/*'],
  limit: 5,
});

const watcher = evocrawl.watcher(id, { kind: 'crawl', pollInterval: 2, timeout: 120 });

watcher.on('document', (doc) => {
  console.log('DOC', doc);
});

watcher.on('error', (err) => {
  console.error('ERR', err?.error || err);
});

watcher.on('done', (state) => {
  console.log('DONE', state.status);
});

// 監視を開始（WS と HTTP のフォールバック）
await watcher.start();

ページネーション

Evocrawl の /crawl と batch の各エンドポイントは、追加のデータがある場合に next URL を返します。Node SDK はデフォルトで自動ページネーションを行い、すべてのドキュメントを集約します。その場合は next が null になります。自動ページネーションを無効にしたり、上限を設定したりできます。

クロール

最も手軽なのはウェイター方式の crawl を使うことです。あるいはジョブを開始して、ページングを手動で行ってください。

シンプルなクロール（自動ページ送り、デフォルト）

既定のフローはウェブサイトのクロールを参照してください。

ページネーション制御付きの手動クロール（単一ページ）

ジョブを開始し、autoPaginate: false を指定して1ページずつ取得します。

Node

const crawlStart = await evocrawl.startCrawl('https://docs.evocrawl.com', { limit: 5 });
const crawlJobId = crawlStart.id;

const crawlSingle = await evocrawl.getCrawlStatus(crawlJobId, { autoPaginate: false });
console.log('単一ページのクロール:', crawlSingle.status, 'ドキュメント数:', crawlSingle.data.length, '次:', crawlSingle.next);

制限付きの手動クロール（自動ページネーション + 早期停止）

自動ページネーションはオンのまま、maxPages、maxResults、または maxWaitTime で早めに停止します。

Node

const crawlLimited = await evocrawl.getCrawlStatus(crawlJobId, {
  autoPaginate: true,
  maxPages: 2,
  maxResults: 50,
  maxWaitTime: 15,
});
console.log('クロール制限:', crawlLimited.status, 'ドキュメント数:', crawlLimited.data.length, '次:', crawlLimited.next);

バッチスクレイプ

waiter メソッド batchScrape を使うか、ジョブを開始して手動でページングします。

シンプルなバッチスクレイプ（自動ページネーション、デフォルト）

既定のフローは Batch Scrape を参照してください。

ページネーション制御による手動バッチスクレイプ（単一ページ）

ジョブを開始し、autoPaginate: false を指定して1ページずつ取得します。

Node

const batchStart = await evocrawl.startBatchScrape([
  'https://docs.evocrawl.com',
  'https://evocrawl.com',
], { options: { formats: ['markdown'] } });
const batchJobId = batchStart.id;

const batchSingle = await evocrawl.getBatchScrapeStatus(batchJobId, { autoPaginate: false });
console.log('バッチ単一ページ:', batchSingle.status, 'ドキュメント数:', batchSingle.data.length, '次:', batchSingle.next);

制限付きの手動バッチスクレイプ（自動ページネーション＋早期停止）

自動ページネーションは有効のまま、maxPages、maxResults、または maxWaitTime で早期停止します。

Node

const batchLimited = await evocrawl.getBatchScrapeStatus(batchJobId, {
  autoPaginate: true,
  maxPages: 2,
  maxResults: 100,
  maxWaitTime: 20,
});
console.log('バッチ制限:', batchLimited.status, 'ドキュメント:', batchLimited.data.length, '次:', batchLimited.next);

ブラウザ

クラウドブラウザセッションを起動し、リモートでコードを実行します。

セッションを作成する

Node

import Evocrawl from '@mendable/evocrawl-js';

const evocrawl = new Evocrawl({ apiKey: "fc-YOUR-API-KEY" });

const session = await evocrawl.browser({ ttl: 600 });
console.log(session.id);          // セッションID
console.log(session.cdpUrl);      // wss://cdp-proxy.evocrawl.com/cdp/...
console.log(session.liveViewUrl); // https://liveview.evocrawl.com/...

コードの実行

Node

const result = await evocrawl.browserExecute(session.id, {
  code: 'await page.goto("https://news.ycombinator.com")\ntitle = await page.title()\nprint(title)',
});
console.log(result.result); // "Hacker News"

Python の代わりに JavaScript を実行する:

Node

const result = await evocrawl.browserExecute(session.id, {
  code: 'await page.goto("https://example.com"); const t = await page.title(); console.log(t);',
  language: "node",
});

agent-browser 経由で Bash を実行する:

Node

const result = await evocrawl.browserExecute(session.id, {
  code: "agent-browser open https://example.com && agent-browser snapshot",
  language: "bash",
});

プロファイル

ブラウザの状態（Cookie、localStorage など）をセッション間で保存して再利用できます:

Node

const session = await evocrawl.browser({
  ttl: 600,
  profile: {
    name: "my-profile",
    saveChanges: true,
  },
});

CDP 経由で接続する

Playwright をフルに制御するには、CDP URL を使用して直接接続します。

Node

import { chromium } from "playwright";

const browser = await chromium.connectOverCDP(session.cdpUrl);
const context = browser.contexts()[0];
const page = context.pages()[0] || await context.newPage();

await page.goto("https://example.com");
console.log(await page.title());

await browser.close();

セッションの一覧表示とクローズ

Node

// アクティブなセッションを一覧表示
const { sessions } = await evocrawl.listBrowsers({ status: "active" });
for (const s of sessions) {
  console.log(s.id, s.status, s.createdAt);
}

// Close a session
await evocrawl.deleteBrowser(session.id);

スクレイプに紐づくインタラクティブセッション

スクレイプのジョブIDを使用すると、そのスクレイプで再現されたページコンテキストに対して引き続き操作できます。

interact(jobId, {...}) は、スクレイプに紐づくブラウザセッション内でコードを実行します。
最初の interact 呼び出しでは、スクレイプコンテキストからセッションが自動的に初期化されます。
同じジョブIDに対する追加の interact 呼び出しでは、そのライブなブラウザ状態が再利用されます。
stopInteraction(jobId) は、操作が完了したらインタラクティブセッションを停止します。

Node

const doc = await evocrawl.scrape("https://example.com", {
  actions: [{ type: "click", selector: "a[href='/pricing']" }],
});

const scrapeJobId = doc.metadata?.scrapeId;
if (!scrapeJobId) throw new Error("Missing scrape job id");

const run = await evocrawl.interact(scrapeJobId, {
  code: "console.log(await page.url())",
  language: "node",
  timeout: 60,
});
console.log(run.stdout);

await evocrawl.stopInteraction(scrapeJobId);

エラーハンドリング

この SDK は EvoCrawl API から返されるエラーを処理し、適切な例外を送出します。リクエスト中にエラーが発生した場合は、わかりやすいエラーメッセージ付きの例外が送出されます。上記の例では、try/catch ブロックを使ってこれらのエラーを処理する方法を示しています。

EvoCrawl API キーが必要な AI agent ですか？自動オンボーディング手順については、evocrawl.dev/agent-onboarding/SKILL.md を参照してください。

全体像

公式

Node

インストール

使い方

URLをスクレイピングする

ウェブサイトのクロール

サイトマップのみクロール

クローリングを開始

クロールのステータス確認

クロールのキャンセル

ウェブサイトのマッピング

WebSocket を使ったサイトのクロール

クロール

バッチスクレイプ

ブラウザ

セッションを作成する

コードの実行

プロファイル

CDP 経由で接続する

セッションの一覧表示とクローズ

スクレイプに紐づくインタラクティブセッション

エラーハンドリング

​インストール

​使い方

​URLをスクレイピングする

​ウェブサイトのクロール

​サイトマップのみクロール

​クローリングを開始

​クロールのステータス確認

​クロールのキャンセル

​ウェブサイトのマッピング

​WebSocket を使ったサイトのクロール

​ページネーション

​クロール

シンプルなクロール（自動ページ送り、デフォルト）

ページネーション制御付きの手動クロール（単一ページ）

制限付きの手動クロール（自動ページネーション + 早期停止）

​バッチスクレイプ

シンプルなバッチスクレイプ（自動ページネーション、デフォルト）

ページネーション制御による手動バッチスクレイプ（単一ページ）

制限付きの手動バッチスクレイプ（自動ページネーション＋早期停止）

​ブラウザ

​セッションを作成する

​コードの実行

​プロファイル

​CDP 経由で接続する

​セッションの一覧表示とクローズ

​スクレイプに紐づくインタラクティブセッション

​エラーハンドリング

インストール

使い方

URLをスクレイピングする

ウェブサイトのクロール

サイトマップのみクロール

クローリングを開始

クロールのステータス確認

クロールのキャンセル

ウェブサイトのマッピング

WebSocket を使ったサイトのクロール

ページネーション

クロール

バッチスクレイプ

ブラウザ

セッションを作成する

コードの実行

プロファイル

CDP 経由で接続する

セッションの一覧表示とクローズ

スクレイプに紐づくインタラクティブセッション

エラーハンドリング