Rust SDK | Evocrawl

Instalação

O SDK oficial do Evocrawl para Rust é mantido no monorepo do Evocrawl em apps/rust-sdk. Para instalar o SDK do Evocrawl para Rust, adicione a dependência do crates.io:

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

Ou instale com o Cargo:

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

Requer Rust 1.70 ou superior.

Uso

Obtenha uma chave de API em evocrawl.com
Defina a chave de API como uma variável de ambiente chamada FIRECRAWL_API_KEY ou passe-a diretamente para Client::new(...)

Aqui está um exemplo rápido com o 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(())
}

Scraping de uma URL

Para fazer scraping de uma única URL, use o 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);
}

Extração JSON

Extraia dados JSON estruturados usando 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)?);

Ou configure a extração JSON diretamente via 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);

Rastreamento de um site

Para rastrear um site e aguardar a conclusão, use 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 um rastreamento

Inicie um job sem aguardar usando 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);

Verificando o status do rastreamento

Verifique o andamento do rastreamento com get_crawl_status.

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

Cancelar um rastreamento

Cancele um rastreamento em execução com cancel_crawl.

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

Verificando erros de rastreamento

Recupere os erros de um job de rastreamento com get_crawl_errors.

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

Mapear um site

Encontre links em um site com 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 um resultado mais simples, com apenas URLs, use map_urls:

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

Busca na Web

Faça uma busca com configurações opcionais usando 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 um método auxiliar que retorna documentos extraídos diretamente:

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

Scraping em lote

Faça scraping de várias URLs em paralelo com 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

Execute um agente com IA usando 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);

Com um schema JSON para resultado estruturado:

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

Sessão interativa vinculada ao scraping

Use um ID do job de scraping para executar código adicional no navegador no mesmo contexto:

interact(...) executa código ou prompts na sessão do navegador vinculada ao scraping.
stop_interaction(...) encerra a sessão interativa quando terminar.

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

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

// Executar código na sessão do navegador
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);

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

// Encerrar a sessão quando concluído
client.stop_interaction(scrape_job_id).await?;

Configuração

Client::new(...) e Client::new_selfhosted(...) criam o cliente.

Opção	Descrição
`Client::new(api_key)`	Cria um cliente para o serviço em nuvem do Evocrawl (`https://api.evocrawl.com`)
`Client::new_selfhosted(api_url, api_key)`	Cria um cliente para uma instância auto-hospedada do Evocrawl

use firecrawl::Client;

// Serviço em nuvem
let client = Client::new("fc-your-api-key")?;

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

// Auto-hospedado sem autenticação
let client = Client::new_selfhosted(
    "http://localhost:3002",
    None::<&str>,
)?;

Variável de ambiente

Defina a variável de ambiente FIRECRAWL_API_KEY em vez de informar a chave diretamente:

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 consulta

Os métodos síncronos (crawl, batch_scrape, agent) consultam o status até a conclusão. Você pode personalizar o intervalo de consulta por meio da struct options:

use firecrawl::CrawlOptions;

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

Tratamento de erros

O SDK usa o enum EvocrawlError, que implementa Error, Debug e Display. Todos os métodos retornam 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),
}

Você é um agente de IA que precisa de uma chave de API do Evocrawl? Veja evocrawl.com/agent-onboarding/SKILL.md para instruções de onboarding automatizado.

Geral

Oficial

Rust

Instalação

Uso

Scraping de uma URL

Extração JSON

Rastreamento de um site

Iniciar um rastreamento

Verificando o status do rastreamento

Cancelar um rastreamento

Verificando erros de rastreamento

Mapear um site

Busca na Web

Scraping em lote

Agente

Sessão interativa vinculada ao scraping

Configuração

Variável de ambiente

Intervalos de consulta

Tratamento de erros

Geral

Oficial

​Instalação

​Uso

​Scraping de uma URL

​Extração JSON

​Rastreamento de um site

​Iniciar um rastreamento

​Verificando o status do rastreamento

​Cancelar um rastreamento

​Verificando erros de rastreamento

​Mapear um site

​Busca na Web

​Scraping em lote

​Agente

​Sessão interativa vinculada ao scraping

​Configuração

​Variável de ambiente

​Intervalos de consulta

​Tratamento de erros

Instalação

Uso

Scraping de uma URL

Extração JSON

Rastreamento de um site

Iniciar um rastreamento

Verificando o status do rastreamento

Cancelar um rastreamento

Verificando erros de rastreamento

Mapear um site

Busca na Web

Scraping em lote

Agente

Sessão interativa vinculada ao scraping

Configuração

Variável de ambiente

Intervalos de consulta

Tratamento de erros