Rust SDK | Firecrawl

Instalación

El SDK oficial de Rust está alojado en el monorepo de Firecrawl, en apps/rust-sdk. Para instalar el SDK de Rust de Firecrawl, 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 firecrawl.dev
Configura la clave de API como una variable de entorno llamada FIRECRAWL_API_KEY o pásala directamente a Client::new(...)

Haz scraping de una página e imprime su contenido en markdown:

use firecrawl::{Client, 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://firecrawl.dev",
        ScrapeOptions {
            formats: Some(vec![Format::Markdown]),
            ..Default::default()
        },
    ).await?;

    println!("{}", doc.markdown.unwrap_or_default());
    Ok(())
}

Las secciones siguientes abarcan el rastreo, el mapeo, la búsqueda y los demás métodos del SDK.

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://firecrawl.dev",
    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);

Procesamiento de archivos subidos

Usa parse para subir un archivo local (.html, .htm, .pdf, .docx, .doc, .odt, .rtf, .xlsx, .xls) como datos de formulario multipart a /v2/parse. El endpoint devuelve un Document con los formatos solicitados. ParseOptions omite intencionadamente los campos exclusivos de scrape que /v2/parse rechaza (como actions, waitFor, location, mobile, screenshot, branding y changeTracking). Crea un ParseFile a partir de bytes en memoria o directamente desde una ruta:

use firecrawl::{Client, ParseFile, ParseFormat, ParseOptions};

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

    let file = ParseFile::from_bytes(
        "upload.html",
        b"<!DOCTYPE html><html><body><h1>Rust Parse</h1></body></html>".to_vec(),
    )
    .with_content_type("text/html");

    let options = ParseOptions {
        formats: Some(vec![ParseFormat::Markdown, ParseFormat::Html]),
        only_main_content: Some(true),
        ..Default::default()
    };

    let doc = client.parse(file, Some(options)).await?;
    println!("{}", doc.markdown.unwrap_or_default());
    Ok(())
}

O lee el archivo desde el disco y omite las opciones:

use firecrawl::{Client, ParseFile};

let client = Client::new("fc-YOUR-API-KEY")?;
let file = ParseFile::from_path("./report.pdf")?;

let doc = client.parse(file, None).await?;
println!("{}", doc.markdown.unwrap_or_default());

`ParseFile`

Constructor	Descripción
`ParseFile::from_bytes(filename, bytes)`	Crea una instancia a partir de un nombre de archivo y bytes en memoria
`ParseFile::from_path(path)`	Lee los bytes desde el disco y obtiene el nombre del archivo
`.with_content_type(content_type)`	Añade una sugerencia de tipo MIME (p. ej., `text/html`, `application/pdf`)

`ParseOptions`

Campos admitidos (todos opcionales, en camelCase en la solicitud):

formats: Vec<ParseFormat> — cualquiera de Markdown, Html, RawHtml, Links, Images, Summary, Json, Attributes
only_main_content: bool
include_tags: Vec<String> / exclude_tags: Vec<String>
headers: HashMap<String, String>
timeout: u32 (ms)
parsers: Vec<ParserConfig> (p. ej., configuración del analizador de PDF)
skip_tls_verification: bool
remove_base64_images: bool
fast_mode: bool
block_ads: bool
proxy: ParseProxyType (Basic o Auto)
json_options: JsonOptions
attribute_selectors: Vec<AttributeSelector>
zero_data_retention: bool
integration: String, origin: String, use_mock: String

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://firecrawl.dev",
    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://firecrawl.dev",
    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://firecrawl.dev",
    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://firecrawl.dev", 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://firecrawl.dev".to_string(),
    "https://firecrawl.dev/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 Firecrawl 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://firecrawl.dev".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 Firecrawl (`https://api.firecrawl.dev`)
`Client::new_selfhosted(api_url, api_key)`	Crea un cliente para una instancia autogestionada de Firecrawl

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 FirecrawlError, que implementa Error, Debug y Display. Todos los métodos devuelven Result<T, FirecrawlError>.

use firecrawl::{Client, FirecrawlError};

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

¿Eres un agente de IA que necesita una clave de API de Firecrawl? Consulta firecrawl.dev/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

Procesamiento de archivos subidos

`ParseFile`

`ParseOptions`

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

Documentation Index

​Instalación

​Uso

​Hacer scraping de una URL

​Extracción JSON

​Procesamiento de archivos subidos

​ParseFile

​ParseOptions

​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

Procesamiento de archivos subidos

`ParseFile`

`ParseOptions`

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