Node SDK | Evocrawl

Haz scraping de páginas individuales, rastrea sitios completos y mapea URL desde tu aplicación Node.js. El SDK gestiona la paginación, los reintentos y la consulta asíncrona del estado de los trabajos para que puedas centrarte en trabajar con los datos devueltos.

Instalación

Para instalar el SDK de Evocrawl para Node, puedes usar npm:

Node

# npm install @mendable/evocrawl-js

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

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

Uso

Obtén una clave de API en evocrawl.dev
Define la clave de API como una variable de entorno llamada EVOCRAWL_API_KEY o pásala como parámetro a la clase EvocrawlApp.

Aquí tienes un ejemplo de cómo usar el SDK con manejo de errores:

Node

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

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

// Extraer datos de un sitio web
const scrapeResponse = await evocrawl.scrape('https://evocrawl.com', {
  formats: ['markdown', 'html'],
});

console.log(scrapeResponse)

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

console.log(crawlResponse)

Extracción de una URL

Para extraer una única URL con manejo de errores, usa el método scrapeUrl. Recibe la URL como parámetro y devuelve los datos extraídos como un diccionario.

Node.js

// Extraer un sitio web:
const scrapeResult = await evocrawl.scrape('evocrawl.com', { formats: ['markdown', 'html'] });

console.log(scrapeResult)

Rastreo de un sitio web

Para rastrear un sitio web con manejo de errores, usa el método crawlUrl. Recibe la URL inicial y parámetros opcionales como argumentos. El argumento params te permite especificar opciones adicionales para la tarea de rastreo, como el número máximo de páginas a rastrear, los dominios permitidos y el formato de salida. Consulta Paginación para la paginación automática o manual y la configuración de límites.

Node

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

Rastreo solo del sitemap

Usa sitemap: "only" para rastrear únicamente las URL del sitemap (la URL inicial siempre se incluye y se omite la detección de enlaces HTML).

Node

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

Iniciar un rastreo

Inicia un trabajo sin esperar usando startCrawl. Devuelve un ID de trabajo que puedes usar para comprobar el estado. Usa crawl cuando necesites un proceso bloqueante que espere hasta la finalización. Consulta Paginación para el comportamiento y los límites de paginación.

Node

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

Verificar el estado del rastreo

Para verificar el estado de un trabajo de rastreo con manejo de errores, usa el método checkCrawlStatus. Recibe el ID como parámetro y devuelve el estado actual del trabajo de rastreo.

Node.js

const estado = await evocrawl.getCrawlStatus("<id-de-rastreo>");
console.log(estado);

Cancelar un rastreo

Para cancelar un trabajo de rastreo, usa el método cancelCrawl. Recibe como parámetro el ID del trabajo iniciado con startCrawl y devuelve el estado de la cancelación.

Node

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

Mapear un sitio web

Para mapear un sitio web con manejo de errores, utiliza el método mapUrl. Recibe la URL inicial como parámetro y devuelve los datos del mapeo como un diccionario.

Node

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

Rastreo de un sitio web con WebSockets

Para rastrear un sitio web con WebSockets, usa el método crawlUrlAndWatch. Recibe la URL inicial y parámetros opcionales como argumentos. El argumento params te permite especificar opciones adicionales para la tarea de rastreo, como el número máximo de páginas a rastrear, los dominios permitidos y el formato de salida.

Node

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

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

// Inicia un rastreo y luego míralo
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);
});

// Comienza a mirar (WS con alternativa HTTP)
await watcher.start();

Paginación

Los puntos de conexión de Evocrawl para crawl y batch devuelven una URL next cuando hay más datos disponibles. El SDK de Node realiza la paginación automáticamente por defecto y agrega todos los documentos; en ese caso, next será null. Puedes desactivar la paginación automática o establecer límites.

Rastreo

Usa el método auxiliar crawl para la forma más sencilla, o inicia un job y pagina manualmente.

Rastreo simple (paginación automática, por defecto)

Consulta el flujo por defecto en Rastrear un sitio web.

Rastreo manual con control de paginación (una sola página)

Inicia un trabajo y luego recupera una página a la vez con autoPaginate: false.

Nodo

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('rastreo de una sola página:', crawlSingle.status, 'docs:', crawlSingle.data.length, 'siguiente:', crawlSingle.next);

Rastreo manual con límites (paginación automática + parada anticipada)

Mantén la paginación automática activada, pero deténla antes con maxPages, maxResults o maxWaitTime.

Node

const crawlLimited = await evocrawl.getCrawlStatus(crawlJobId, {
  autoPaginate: true,
  maxPages: 2,
  maxResults: 50,
  maxWaitTime: 15,
});
console.log('rastreo limitado:', crawlLimited.status, 'docs:', crawlLimited.data.length, 'siguiente:', crawlLimited.next);

Scrape por lotes

Usa el método waiter batchScrape, o inicia un job y pagina manualmente.

Raspado por lotes simple (paginación automática, predeterminado)

Consulta el flujo predeterminado en Raspado por lotes.

Raspado manual por lotes con control de paginación (una sola página)

Inicia un job y luego recupera una página a la vez con 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('lote, una sola página:', batchSingle.status, 'docs:', batchSingle.data.length, 'siguiente:', batchSingle.next);

Extracción manual por lotes con límites (paginación automática + detención anticipada)

Mantén la paginación automática activada, pero deténla antes con maxPages, maxResults o maxWaitTime.

Node

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

Browser

Inicia sesiones de navegador en la nube y ejecuta código de forma remota.

Crear una sesión

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

Ejecutar código

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"

Ejecutar JavaScript en lugar de 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",
});

Ejecutar Bash con agent-browser:

Node

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

Perfiles

Guarda y reutiliza el estado del navegador (cookies, localStorage, etc.) entre sesiones:

Node

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

Conectar mediante CDP

Para obtener control completo de Playwright, conecta directamente usando la URL de 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();

Listar y cerrar sesiones

Node

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

// Cerrar una sesión
await evocrawl.deleteBrowser(session.id);

Sesión interactiva vinculada a scrape

Usa un ID de trabajo de scrape para seguir interactuando con el contexto de la página reproducida de ese scrape:

interact(jobId, {...}) ejecuta código en la sesión del navegador vinculada al scrape.
La primera llamada a interact inicializa automáticamente la sesión a partir del contexto del scrape.
Las llamadas adicionales a interact con el mismo ID de trabajo reutilizan ese estado activo del navegador.
stopInteraction(jobId) detiene la sesión interactiva cuando termines.

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

Manejo de errores

El SDK gestiona los errores devueltos por la API de Evocrawl y arroja las excepciones correspondientes. Si se produce un error durante una solicitud, se generará una excepción con un mensaje descriptivo. Los ejemplos anteriores muestran cómo manejar estos errores con bloques try/catch.

¿Eres un agente de IA que necesita una clave de API de Evocrawl? Consulta evocrawl.dev/agent-onboarding/SKILL.md para obtener instrucciones de incorporación automatizada.

General

Oficial

Node

Instalación

Uso

Extracción de una URL

Rastreo de un sitio web

Rastreo solo del sitemap

Iniciar un rastreo

Verificar el estado del rastreo

Cancelar un rastreo

Mapear un sitio web

Rastreo de un sitio web con WebSockets

Rastreo

Scrape por lotes

Browser

Crear una sesión

Ejecutar código

Perfiles

Conectar mediante CDP

Listar y cerrar sesiones

Sesión interactiva vinculada a scrape

Manejo de errores

​Instalación

​Uso

​Extracción de una URL

​Rastreo de un sitio web

​Rastreo solo del sitemap

​Iniciar un rastreo

​Verificar el estado del rastreo

​Cancelar un rastreo

​Mapear un sitio web

​Rastreo de un sitio web con WebSockets

​Paginación

​Rastreo

Rastreo simple (paginación automática, por defecto)

Rastreo manual con control de paginación (una sola página)

Rastreo manual con límites (paginación automática + parada anticipada)

​Scrape por lotes

Raspado por lotes simple (paginación automática, predeterminado)

Raspado manual por lotes con control de paginación (una sola página)

Extracción manual por lotes con límites (paginación automática + detención anticipada)

​Browser

​Crear una sesión

​Ejecutar código

​Perfiles

​Conectar mediante CDP

​Listar y cerrar sesiones

​Sesión interactiva vinculada a scrape

​Manejo de errores

Instalación

Uso

Extracción de una URL

Rastreo de un sitio web

Rastreo solo del sitemap

Iniciar un rastreo

Verificar el estado del rastreo

Cancelar un rastreo

Mapear un sitio web

Rastreo de un sitio web con WebSockets

Paginación

Rastreo

Scrape por lotes

Browser

Crear una sesión

Ejecutar código

Perfiles

Conectar mediante CDP

Listar y cerrar sesiones

Sesión interactiva vinculada a scrape

Manejo de errores