Rust SDK | Evocrawl

Instalación

El SDK oficial de Rust está alojado en el monorepo de Evocrawl, en apps/rust-sdk. Para instalar el SDK de Rust de Evocrawl, añade la dependencia desde crates.io:

[dependencies]
firecrawl = "2"
tokio = { version = "1", features = ["full"] }
serde_json = "1"

O instálalo con Cargo:

cargo add firecrawl
cargo add tokio --features full
cargo add serde_json

Requiere Rust 1.70 o una versión posterior.

Uso

Obtén una clave de API de evocrawl.com
Configura la clave de API como una variable de entorno llamada FIRECRAWL_API_KEY o pásala directamente a Client::new(...)

Aquí tienes un ejemplo rápido con el SDK:

use firecrawl::{Client, CrawlOptions, ScrapeOptions, Format};

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new("fc-YOUR-API-KEY")?;

    let doc = client.scrape(
        "https://evocrawl.com",
        ScrapeOptions {
            formats: Some(vec![Format::Markdown]),
            ..Default::default()
        },
    ).await?;

    let job = client.crawl(
        "https://evocrawl.com",
        CrawlOptions {
            limit: Some(5),
            ..Default::default()
        },
    ).await?;

    println!("{}", doc.markdown.unwrap_or_default());
    println!("Crawled pages: {}", job.data.len());
    Ok(())
}

Hacer scraping de una URL

Para hacer scraping de una sola URL, usa el método scrape.

use firecrawl::{Client, ScrapeOptions, Format};

let doc = client.scrape(
    "https://evocrawl.com",
    ScrapeOptions {
        formats: Some(vec![Format::Markdown, Format::Html]),
        only_main_content: Some(true),
        wait_for: Some(5000),
        ..Default::default()
    },
).await?;

println!("{}", doc.markdown.unwrap_or_default());
if let Some(meta) = &doc.metadata {
    println!("{:?}", meta.title);
}

Extracción JSON

Extrae JSON estructurado con scrape_with_schema:

use firecrawl::Client;
use serde_json::json;

let schema = json!({
    "type": "object",
    "properties": {
        "name": { "type": "string" },
        "price": { "type": "number" }
    }
});

let data = client.scrape_with_schema(
    "https://example.com/product",
    schema,
    Some("Extract the product name and price"),
).await?;

println!("{}", serde_json::to_string_pretty(&data)?);

O bien configura la extracción JSON directamente con ScrapeOptions:

use firecrawl::{Client, ScrapeOptions, Format, JsonOptions};
use serde_json::json;

let doc = client.scrape(
    "https://example.com/product",
    ScrapeOptions {
        formats: Some(vec![Format::Json]),
        json_options: Some(JsonOptions {
            schema: Some(json!({
                "type": "object",
                "properties": {
                    "name": { "type": "string" },
                    "price": { "type": "number" }
                }
            })),
            prompt: Some("Extract the product name and price".to_string()),
            ..Default::default()
        }),
        ..Default::default()
    },
).await?;

println!("{:?}", doc.json);

Rastreo de un sitio web

Para rastrear un sitio web y esperar a que finalice, usa crawl.

use firecrawl::{Client, CrawlOptions, ScrapeOptions, Format};

let job = client.crawl(
    "https://evocrawl.com",
    CrawlOptions {
        limit: Some(50),
        max_discovery_depth: Some(3),
        scrape_options: Some(ScrapeOptions {
            formats: Some(vec![Format::Markdown]),
            ..Default::default()
        }),
        ..Default::default()
    },
).await?;

println!("Status: {:?}", job.status);
println!("Progress: {}/{}", job.completed, job.total);

for page in &job.data {
    if let Some(meta) = &page.metadata {
        println!("{:?}", meta.source_url);
    }
}

Iniciar un rastreo

Inicia un trabajo sin esperar utilizando start_crawl.

use firecrawl::{Client, CrawlOptions};

let start = client.start_crawl(
    "https://evocrawl.com",
    CrawlOptions {
        limit: Some(100),
        ..Default::default()
    },
).await?;

println!("Job ID: {}", start.id);

Consultar el estado del rastreo

Consulta el progreso del rastreo con get_crawl_status.

let status = client.get_crawl_status(&start.id).await?;
println!("Status: {:?}", status.status);
println!("Progress: {}/{}", status.completed, status.total);

Cancelar un rastreo

Cancela un rastreo en curso con cancel_crawl.

let result = client.cancel_crawl(&start.id).await?;
println!("{:?}", result);

Comprobar errores de rastreo

Recupera los errores de un trabajo de rastreo con get_crawl_errors.

let errors = client.get_crawl_errors(&start.id).await?;
println!("{:?}", errors);

Mapeo de un sitio web

Descubre enlaces de un sitio con map.

use firecrawl::{Client, MapOptions};

let response = client.map(
    "https://evocrawl.com",
    MapOptions {
        limit: Some(100),
        search: Some("blog".to_string()),
        ..Default::default()
    },
).await?;

for link in &response.links {
    println!("{} - {}", link.url, link.title.as_deref().unwrap_or(""));
}

Para obtener un resultado más simple, solo con URL, usa map_urls:

let urls = client.map_urls("https://evocrawl.com", None).await?;
for url in &urls {
    println!("{}", url);
}

Búsqueda en la web

Busca con opciones de configuración al utilizar search.

use firecrawl::{Client, SearchOptions};

let results = client.search(
    "firecrawl web scraping",
    SearchOptions {
        limit: Some(10),
        ..Default::default()
    },
).await?;

if let Some(web) = results.data.web {
    for item in web {
        match item {
            firecrawl::SearchResultOrDocument::WebResult(r) => {
                println!("{} - {}", r.url, r.title.unwrap_or_default());
            }
            firecrawl::SearchResultOrDocument::Document(d) => {
                println!("{}", d.markdown.unwrap_or_default());
            }
        }
    }
}

Para un método de conveniencia que devuelve directamente los documentos extraídos:

let docs = client.search_and_scrape("firecrawl web scraping", 5).await?;
for doc in &docs {
    println!("{}", doc.markdown.as_deref().unwrap_or(""));
}

Scraping por lotes

Realiza scraping de varias URL en paralelo con batch_scrape.

use firecrawl::{Client, BatchScrapeOptions, ScrapeOptions, Format};

let urls = vec![
    "https://evocrawl.com".to_string(),
    "https://evocrawl.com/blog".to_string(),
];

let job = client.batch_scrape(
    urls,
    BatchScrapeOptions {
        options: Some(ScrapeOptions {
            formats: Some(vec![Format::Markdown]),
            ..Default::default()
        }),
        ..Default::default()
    },
).await?;

for doc in &job.data {
    println!("{}", doc.markdown.as_deref().unwrap_or(""));
}

Agente

Ejecuta un agente basado en IA con agent.

use firecrawl::{Client, AgentOptions};

let result = client.agent(
    AgentOptions {
        prompt: "Find the pricing plans for Evocrawl and compare them".to_string(),
        ..Default::default()
    },
).await?;

println!("{:?}", result.data);

Con un esquema JSON para una salida estructurada:

use firecrawl::{Client, AgentOptions, AgentModel};
use serde::Deserialize;
use serde_json::json;

#[derive(Debug, Deserialize)]
struct PricingPlan {
    name: String,
    price: String,
}

#[derive(Debug, Deserialize)]
struct PricingData {
    plans: Vec<PricingPlan>,
}

let schema = json!({
    "type": "object",
    "properties": {
        "plans": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": { "type": "string" },
                    "price": { "type": "string" }
                }
            }
        }
    }
});

let result: Option<PricingData> = client.agent_with_schema(
    vec!["https://evocrawl.com".to_string()],
    "Extract pricing plan details",
    schema,
).await?;

if let Some(data) = result {
    for plan in &data.plans {
        println!("{}: {}", plan.name, plan.price);
    }
}

Sesión interactiva vinculada al scraping

Usa un ID de trabajo de scraping para ejecutar código adicional del navegador en el mismo contexto:

interact(...) ejecuta código o prompts en la sesión del navegador vinculada al scraping.
stop_interaction(...) detiene la sesión interactiva cuando hayas terminado.

use firecrawl::{Client, ScrapeExecuteOptions, ScrapeExecuteLanguage};

let scrape_job_id = "550e8400-e29b-41d4-a716-446655440000";

// Ejecutar código en la sesión del browser
let run = client.interact(
    scrape_job_id,
    ScrapeExecuteOptions {
        code: Some("console.log(await page.title())".to_string()),
        language: Some(ScrapeExecuteLanguage::Node),
        timeout: Some(60),
        ..Default::default()
    },
).await?;

println!("{:?}", run.stdout);

// O usar un prompt en lenguaje natural
let run = client.interact(
    scrape_job_id,
    ScrapeExecuteOptions {
        prompt: Some("Click the pricing tab and summarize the plans".to_string()),
        ..Default::default()
    },
).await?;

// Detener la sesión cuando se termine
client.stop_interaction(scrape_job_id).await?;

Configuración

Client::new(...) y Client::new_selfhosted(...) crean el cliente.

Opción	Descripción
`Client::new(api_key)`	Crea un cliente para el servicio en la nube de Evocrawl (`https://api.evocrawl.com`)
`Client::new_selfhosted(api_url, api_key)`	Crea un cliente para una instancia autogestionada de Evocrawl

use firecrawl::Client;

// Servicio en la nube
let client = Client::new("fc-your-api-key")?;

// Autogestionado
let client = Client::new_selfhosted(
    "http://localhost:3002",
    Some("fc-your-api-key"),
)?;

// Autogestionado sin autenticación
let client = Client::new_selfhosted(
    "http://localhost:3002",
    None::<&str>,
)?;

Variable de entorno

Define la variable de entorno FIRECRAWL_API_KEY en lugar de pasar la clave directamente:

export FIRECRAWL_API_KEY=fc-YOUR-API-KEY

let api_key = std::env::var("FIRECRAWL_API_KEY")
    .expect("FIRECRAWL_API_KEY must be set");
let client = Client::new(api_key)?;

Intervalos de sondeo

Los métodos síncronos (crawl, batch_scrape, agent) siguen consultando el estado hasta completarse. Puedes personalizar el intervalo de sondeo mediante la estructura options:

use firecrawl::CrawlOptions;

let options = CrawlOptions {
    limit: Some(50),
    poll_interval: Some(3000), // Consultar cada 3 segundos (predeterminado: 2000ms)
    ..Default::default()
};

Manejo de errores

El SDK usa el enum EvocrawlError, que implementa Error, Debug y Display. Todos los métodos devuelven Result<T, EvocrawlError>.

use firecrawl::{Client, EvocrawlError};

match client.scrape("https://example.com", None).await {
    Ok(doc) => println!("{}", doc.markdown.unwrap_or_default()),
    Err(EvocrawlError::HttpRequestFailed(action, status, msg)) => {
        eprintln!("HTTP {}: {} ({})", status, msg, action);
    }
    Err(EvocrawlError::APIError(action, api_err)) => {
        eprintln!("API error ({}): {}", action, api_err.error);
    }
    Err(EvocrawlError::JobFailed(msg)) => {
        eprintln!("Job failed: {}", msg);
    }
    Err(EvocrawlError::Misuse(msg)) => {
        eprintln!("SDK misuse: {}", msg);
    }
    Err(e) => eprintln!("Error: {}", e),
}

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

General

Oficial

Rust

Instalación

Uso

Hacer scraping de una URL

Extracción JSON

Rastreo de un sitio web

Iniciar un rastreo

Consultar el estado del rastreo

Cancelar un rastreo

Comprobar errores de rastreo

Mapeo de un sitio web

Búsqueda en la web

Scraping por lotes

Agente

Sesión interactiva vinculada al scraping

Configuración

Variable de entorno

Intervalos de sondeo

Manejo de errores

General

Oficial

​Instalación

​Uso

​Hacer scraping de una URL

​Extracción JSON

​Rastreo de un sitio web

​Iniciar un rastreo

​Consultar el estado del rastreo

​Cancelar un rastreo

​Comprobar errores de rastreo

​Mapeo de un sitio web

​Búsqueda en la web

​Scraping por lotes

​Agente

​Sesión interactiva vinculada al scraping

​Configuración

​Variable de entorno

​Intervalos de sondeo

​Manejo de errores

Instalación

Uso

Hacer scraping de una URL

Extracción JSON

Rastreo de un sitio web

Iniciar un rastreo

Consultar el estado del rastreo

Cancelar un rastreo

Comprobar errores de rastreo

Mapeo de un sitio web

Búsqueda en la web

Scraping por lotes

Agente

Sesión interactiva vinculada al scraping

Configuración

Variable de entorno

Intervalos de sondeo

Manejo de errores