SDK Node | Evocrawl

Scrapez des pages individuelles, lancez un crawl sur des sites entiers et cartographiez les URL depuis votre application Node.js. Le SDK gère la pagination, les nouvelles tentatives et l’interrogation asynchrone des tâches pour que vous puissiez vous concentrer sur l’exploitation des données retournées.

Installation

Pour installer le SDK Evocrawl pour Node, vous pouvez utiliser npm :

Node

# npm install @mendable/evocrawl-js

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

const evocrawl = new Evocrawl({ apiKey: "fc-VOTRE-CLÉ-API" });

Utilisation

Récupérez une clé d’API sur evocrawl.dev
Définissez la clé d’API comme variable d’environnement nommée EVOCRAWL_API_KEY, ou transmettez-la en paramètre à la classe EvocrawlApp.

Voici un exemple d’utilisation du SDK avec gestion des erreurs :

Node

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

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

// Récupérer le contenu d’un site web
const scrapeResponse = await evocrawl.scrape('https://evocrawl.com', {
  formats: ['markdown', 'html'],
});

console.log(scrapeResponse)

// Explorer un site web
const crawlResponse = await evocrawl.crawl('https://evocrawl.com', {
  limit: 100,
  scrapeOptions: {
    formats: ['markdown', 'html'],
  }
});

console.log(crawlResponse)

Scraper une URL

Pour récupérer le contenu d’une URL avec gestion des erreurs, utilisez la méthode scrapeUrl. Elle prend l’URL en paramètre et renvoie les données récupérées sous forme de dictionnaire.

Node.js

// Extraire le contenu d’un site :
const scrapeResult = await evocrawl.scrape('evocrawl.com', { formats: ['markdown', 'html'] });

console.log(scrapeResult)

Explorer un site web

Pour explorer un site web avec gestion des erreurs, utilisez la méthode crawlUrl. Elle prend en arguments l’URL de départ et des paramètres optionnels. L’argument params vous permet de définir des options supplémentaires pour la tâche d’exploration, comme le nombre maximal de pages à explorer, les domaines autorisés et le format de sortie. Voir Pagination pour la pagination automatique/manuelle et la limitation.

Node.js

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

Crawl uniquement via le sitemap

Utilisez sitemap: "only" pour explorer uniquement les URL du sitemap (l’URL de départ est toujours incluse et la découverte de liens HTML est désactivée).

Node

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

Démarrer un crawl

Lancez une tâche sans attendre avec startCrawl. Elle renvoie un ID de tâche que vous pouvez utiliser pour vérifier l’état. Utilisez crawl si vous voulez un « waiter » qui bloque jusqu’à la fin. Voir Pagination pour le comportement de pagination et les limites.

Node

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

Vérifier l’état du crawl

Pour consulter l’état d’un job de crawl avec gestion des erreurs, utilisez la méthode checkCrawlStatus. Elle prend l’ID en paramètre et renvoie l’état actuel du job de crawl.

Node

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

Annuler un crawl

Pour annuler une tâche de crawl, utilisez la méthode cancelCrawl. Elle prend l’ID de la tâche lancée par startCrawl en paramètre et renvoie l’état de l’annulation.

Node

const ok = await evocrawl.cancelCrawl("<crawl-id>");
console.log("Annulé :", ok);

Cartographier un site web

Pour cartographier un site web avec gestion des erreurs, utilisez la méthode mapUrl. Elle prend l’URL de départ en paramètre et renvoie les données cartographiées sous forme de dictionnaire.

Node.js

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

Explorer un site web avec WebSockets

Pour explorer un site web avec WebSockets, utilisez la méthode crawlUrlAndWatch. Elle prend en arguments l’URL de départ et des paramètres optionnels. L’argument params permet de définir des options supplémentaires pour le job d’exploration, comme le nombre maximal de pages à explorer, les domaines autorisés et le format de sortie.

Node

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

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

// Lancer un crawl puis le suivre
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('TERMINÉ', state.status);
});

// Démarrer l’observation (WS avec solution de repli HTTP)
await watcher.start();

Pagination

Les points de terminaison Evocrawl pour crawl et batch renvoient une URL next lorsqu’il reste des données. Le SDK Node effectue, par défaut, une pagination automatique et agrège tous les documents ; dans ce cas, next vaut null. Vous pouvez désactiver la pagination automatique ou définir des limites.

Crawl

Utilisez la méthode d’attente crawl pour la solution la plus simple, ou démarrez un job et paginez manuellement.

Exploration simple (pagination automatique, par défaut)

Voir le flux par défaut dans Exploration d’un site web.

Crawl manuel avec contrôle de la pagination (page unique)

Lancez un job, puis récupérez les pages une par une avec autoPaginate: false.

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('exploration d’une seule page :', crawlSingle.status, 'docs :', crawlSingle.data.length, 'suivant :', crawlSingle.next);

Exploration manuelle avec limites (pagination automatique + arrêt anticipé)

Conservez la pagination automatique activée, mais arrêtez plus tôt avec maxPages, maxResults ou maxWaitTime.

Node

const crawlLimited = await evocrawl.getCrawlStatus(crawlJobId, {
  autoPaginate: true,
  maxPages: 2,
  maxResults: 50,
  maxWaitTime: 15,
});
console.log('exploration limitée :', crawlLimited.status, 'docs :', crawlLimited.data.length, 'suivant :', crawlLimited.next);

Scrape par lots

Utilisez la méthode du waiter batchScrape, ou lancez un job et paginez manuellement.

Collecte par lots simple (pagination automatique, par défaut)

Voir le flux par défaut dans Batch Scrape.

Scraping par lots manuel avec contrôle de la pagination (page unique)

Lancez un job, puis récupérez les pages une par une avec autoPaginate: false.

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('lot page unique :', batchSingle.status, 'docs :', batchSingle.data.length, 'suivant :', batchSingle.next);

Scrape manuel par lots avec limites (pagination automatique + arrêt anticipé)

Laissez la pagination automatique activée, mais arrêtez plus tôt avec maxPages, maxResults ou maxWaitTime.

Node

const batchLimited = await evocrawl.getBatchScrapeStatus(batchJobId, {
  autoPaginate: true,
  maxPages: 2,
  maxResults: 100,
  maxWaitTime: 20,
});
console.log('lot limité :', batchLimited.status, 'docs :', batchLimited.data.length, 'suivant :', batchLimited.next);

Navigateur

Démarrez des sessions de navigateur dans le cloud et exécutez du code à distance.

Créer une session

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 de session
console.log(session.cdpUrl);      // wss://cdp-proxy.evocrawl.com/cdp/...
console.log(session.liveViewUrl); // https://liveview.evocrawl.com/...

Exécuter du code

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"

Exécutez du JavaScript plutôt que du Python :

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",
});

Exécuter Bash avec agent-browser :

Node

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

Profils

Enregistrez et réutilisez l’état du navigateur (cookies, localStorage, etc.) d’une session à l’autre :

Node

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

Connexion via le CDP

Pour bénéficier d’un contrôle complet via Playwright, connectez-vous directement à l’aide de l’URL CDP :

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();

Lister et fermer les sessions

Node

// Lister les sessions actives
const { sessions } = await evocrawl.listBrowsers({ status: "active" });
for (const s of sessions) {
  console.log(s.id, s.status, s.createdAt);
}

// Fermer une session
await evocrawl.deleteBrowser(session.id);

Session interactive liée au scrape

Utilisez un ID de tâche de scrape pour continuer à interagir avec le contexte de page restauré à partir de ce scrape :

interact(jobId, {...}) exécute du code dans la session de navigateur liée au scrape.
Le premier appel à interact initialise automatiquement la session à partir du contexte de scrape.
Les appels suivants à interact sur le même ID de tâche réutilisent cet état actif du navigateur.
stopInteraction(jobId) arrête la session interactive lorsque vous avez terminé.

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);

Gestion des erreurs

Le SDK gère les erreurs renvoyées par l’API Evocrawl et déclenche les exceptions appropriées. Si une erreur survient lors d’une requête, une exception est levée avec un message d’erreur explicite. Les exemples ci-dessus illustrent la gestion de ces erreurs au moyen de blocs try/catch.

Êtes-vous un agent d’IA qui a besoin d’une clé d’API Evocrawl ? Consultez evocrawl.dev/agent-onboarding/SKILL.md pour obtenir des instructions d’intégration automatisée.

Global

Officiel

Node

Installation

Utilisation

Scraper une URL

Explorer un site web

Crawl uniquement via le sitemap

Démarrer un crawl

Vérifier l’état du crawl

Annuler un crawl

Cartographier un site web

Explorer un site web avec WebSockets

Crawl

Scrape par lots

Navigateur

Créer une session

Exécuter du code

Profils

Connexion via le CDP

Lister et fermer les sessions

Session interactive liée au scrape

Gestion des erreurs

​Installation

​Utilisation

​Scraper une URL

​Explorer un site web

​Crawl uniquement via le sitemap

​Démarrer un crawl

​Vérifier l’état du crawl

​Annuler un crawl

​Cartographier un site web

​Explorer un site web avec WebSockets

​Pagination

​Crawl

Exploration simple (pagination automatique, par défaut)

Crawl manuel avec contrôle de la pagination (page unique)

Exploration manuelle avec limites (pagination automatique + arrêt anticipé)

​Scrape par lots

Collecte par lots simple (pagination automatique, par défaut)

Scraping par lots manuel avec contrôle de la pagination (page unique)

Scrape manuel par lots avec limites (pagination automatique + arrêt anticipé)

​Navigateur

​Créer une session

​Exécuter du code

​Profils

​Connexion via le CDP

​Lister et fermer les sessions

​Session interactive liée au scrape

​Gestion des erreurs

Installation

Utilisation

Scraper une URL

Explorer un site web

Crawl uniquement via le sitemap

Démarrer un crawl

Vérifier l’état du crawl

Annuler un crawl

Cartographier un site web

Explorer un site web avec WebSockets

Pagination

Crawl

Scrape par lots

Navigateur

Créer une session

Exécuter du code

Profils

Connexion via le CDP

Lister et fermer les sessions

Session interactive liée au scrape

Gestion des erreurs