> ## Documentation Index
> Fetch the complete documentation index at: https://docs.evocrawl.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Node

> Scrapez, crawlez et extrayez des données structurées depuis des sites web avec le SDK Node de 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.

<div id="installation">
  ## Installation
</div>

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

```js Node theme={null}
# npm install @mendable/evocrawl-js

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

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

<div id="usage">
  ## Utilisation
</div>

1. Récupérez une clé d’API sur [evocrawl.dev](https://evocrawl.com)
2. 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 :

```js Node theme={null}
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)
```

<div id="scraping-a-url">
  ### Scraper une URL
</div>

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.

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

console.log(scrapeResult)
```

<div id="crawling-a-website">
  ### Explorer un site web
</div>

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](#pagination) pour la pagination automatique/manuelle et la limitation.

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

<div id="sitemap-only-crawl">
  ### Crawl uniquement via le sitemap
</div>

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

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

<div id="start-a-crawl">
  ### Démarrer un crawl
</div>

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](#pagination) pour le comportement de pagination et les limites.

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

<div id="checking-crawl-status">
  ### Vérifier l’état du crawl
</div>

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.

```js Node theme={null}
const status = await evocrawl.getCrawlStatus("<crawl-id>");
console.log(status);
```

<div id="cancelling-a-crawl">
  ### Annuler un crawl
</div>

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.

```js Node theme={null}
const ok = await evocrawl.cancelCrawl("<crawl-id>");
console.log("Annulé :", ok);
```

<div id="mapping-a-website">
  ### Cartographier un site web
</div>

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.

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

<div id="crawling-a-website-with-websockets">
  ### Explorer un site web avec WebSockets
</div>

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.

```js Node theme={null}
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();
```

<div id="pagination">
  ### Pagination
</div>

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.

<div id="crawl">
  #### Crawl
</div>

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

<div id="simple-crawl-auto-pagination-default">
  ##### Exploration simple (pagination automatique, par défaut)
</div>

* Voir le flux par défaut dans [Exploration d’un site web](#crawling-a-website).

<div id="manual-crawl-with-pagination-control-single-page">
  ##### Crawl manuel avec contrôle de la pagination (page unique)
</div>

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

```js Node theme={null}
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);
```

<div id="manual-crawl-with-limits-auto-pagination-early-stop">
  ##### Exploration manuelle avec limites (pagination automatique + arrêt anticipé)
</div>

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

```js Node theme={null}
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);
```

<div id="batch-scrape">
  #### Scrape par lots
</div>

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

<div id="simple-batch-scrape-auto-pagination-default">
  ##### Collecte par lots simple (pagination automatique, par défaut)
</div>

* Voir le flux par défaut dans [Batch Scrape](/fr/features/batch-scrape).

<div id="manual-batch-scrape-with-pagination-control-single-page">
  ##### Scraping par lots manuel avec contrôle de la pagination (page unique)
</div>

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

```js Node theme={null}
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);
```

<div id="manual-batch-scrape-with-limits-auto-pagination-early-stop">
  ##### Scrape manuel par lots avec limites (pagination automatique + arrêt anticipé)
</div>

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

```js Node theme={null}
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);
```

<div id="browser">
  ## Navigateur
</div>

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

<div id="create-a-session">
  ### Créer une session
</div>

```js Node theme={null}
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/...
```

<div id="execute-code">
  ### Exécuter du code
</div>

```js Node theme={null}
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 :

```js Node theme={null}
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 :

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

<div id="profiles">
  ### Profils
</div>

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

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

<div id="connect-via-cdp">
  ### Connexion via le CDP
</div>

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

```js Node theme={null}
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();
```

<div id="list-close-sessions">
  ### Lister et fermer les sessions
</div>

```js Node theme={null}
// 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);
```

<div id="scrape-bound-interactive-session">
  ### Session interactive liée au scrape
</div>

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é.

```js Node theme={null}
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);
```

<div id="error-handling">
  ## Gestion des erreurs
</div>

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](https://www.evocrawl.com/agent-onboarding/SKILL.md) pour obtenir des instructions d’intégration automatisée.