SDK Ruby | Firecrawl

Instalação

O SDK Ruby oficial é mantido no monorepo do Firecrawl em apps/ruby-sdk. Para instalar o SDK Ruby do Firecrawl, adicione-o ao seu projeto:

Bundler
Gem install

Adicione ao seu Gemfile:

gem "firecrawl-sdk", "~> 1.0"

Em seguida, execute:

bundle install

gem install firecrawl-sdk

Requer Ruby 3.0 ou superior.

Uso

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

Aqui está um exemplo rápido usando a API atual do SDK:

require "firecrawl"

client = Firecrawl::Client.from_env

doc = client.scrape(
  "https://firecrawl.dev",
  Firecrawl::Models::ScrapeOptions.new(formats: ["markdown"])
)

job = client.crawl(
  "https://firecrawl.dev",
  Firecrawl::Models::CrawlOptions.new(limit: 5)
)

puts doc.markdown
puts "Crawled pages: #{job.data&.size || 0}"

Scraping de uma URL

Para fazer o scraping de uma única URL, use o método scrape.

doc = client.scrape(
  "https://firecrawl.dev",
  Firecrawl::Models::ScrapeOptions.new(
    formats: ["markdown", "html"],
    only_main_content: true,
    wait_for: 5000
  )
)

puts doc.markdown
puts doc.metadata["title"]

Extração JSON

Extraia JSON estruturado pelo endpoint scrape ao incluir o formato json com um prompt e um schema:

doc = client.scrape(
  "https://example.com/product",
  Firecrawl::Models::ScrapeOptions.new(
    formats: [
      {
        "type" => "json",
        "prompt" => "Extract the product name and price",
        "schema" => {
          "type" => "object",
          "properties" => {
            "name" => { "type" => "string" },
            "price" => { "type" => "number" }
          }
        }
      }
    ]
  )
)

puts doc.json

Rastrear um site

Para rastrear um site e aguardar a conclusão, use crawl. Ele consulta automaticamente o status até que o job seja concluído.

job = client.crawl(
  "https://firecrawl.dev",
  Firecrawl::Models::CrawlOptions.new(
    limit: 50,
    max_discovery_depth: 3,
    scrape_options: Firecrawl::Models::ScrapeOptions.new(
      formats: ["markdown"]
    )
  )
)

puts "Status: #{job.status}"
puts "Progress: #{job.completed}/#{job.total}"

job.data&.each do |page|
  puts page.metadata["sourceURL"]
end

Iniciar um rastreamento

Inicie um job sem aguardar usando start_crawl.

response = client.start_crawl(
  "https://firecrawl.dev",
  Firecrawl::Models::CrawlOptions.new(limit: 100)
)

puts "Job ID: #{response.id}"

Verificando o status do rastreamento

Verifique o progresso do rastreamento com get_crawl_status.

status = client.get_crawl_status(response.id)
puts "Status: #{status.status}"
puts "Progress: #{status.completed}/#{status.total}"

Cancelar um rastreamento

Cancele um rastreamento em execução com cancel_crawl.

result = client.cancel_crawl(response.id)
puts result

Mapeando um site

Descubra links em um site com map.

data = client.map(
  "https://firecrawl.dev",
  Firecrawl::Models::MapOptions.new(
    limit: 100,
    search: "blog"
  )
)

data.links&.each do |link|
  puts "#{link["url"]} - #{link["title"]}"
end

Busca na Web

Faça a busca com configurações opcionais usando search.

results = client.search(
  "firecrawl web scraping",
  Firecrawl::Models::SearchOptions.new(limit: 10)
)

results.web&.each do |result|
  puts "#{result["title"]} - #{result["url"]}"
end

Scraping em lote

Faça o scraping de várias URLs em paralelo usando batch_scrape.

job = client.batch_scrape(
  ["https://firecrawl.dev", "https://firecrawl.dev/blog"],
  Firecrawl::Models::BatchScrapeOptions.new(
    options: Firecrawl::Models::ScrapeOptions.new(
      formats: ["markdown"]
    )
  )
)

job.data&.each do |doc|
  puts doc.markdown
end

Agente

Execute um agente de IA com agent.

result = client.agent(
  Firecrawl::Models::AgentOptions.new(
    prompt: "Find the pricing plans for Firecrawl and compare them"
  )
)

puts result.data

Com um schema JSON para resultado estruturado:

result = client.agent(
  Firecrawl::Models::AgentOptions.new(
    prompt: "Extract pricing plan details",
    urls: ["https://firecrawl.dev"],
    schema: {
      "type" => "object",
      "properties" => {
        "plans" => {
          "type" => "array",
          "items" => {
            "type" => "object",
            "properties" => {
              "name" => { "type" => "string" },
              "price" => { "type" => "string" }
            }
          }
        }
      }
    }
  )
)

puts result.data

Uso & métricas

Confira a concorrência e os créditos restantes:

concurrency = client.get_concurrency
puts "Concurrency: #{concurrency.concurrency}/#{concurrency.max_concurrency}"

credits = client.get_credit_usage
puts "Remaining credits: #{credits.remaining_credits}"

Navegador

O SDK para Ruby inclui helpers do Browser Sandbox.

Sessão interativa vinculada ao scraping

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

interact(...) executa código na sessão do navegador vinculada ao scraping (e a inicializa no primeiro uso).
stop_interactive_browser(...) encerra explicitamente a sessão interativa quando você terminar.

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

run = client.interact(
  scrape_job_id,
  "console.log(page.url());",
  language: "node",
  timeout: 60
)

puts run["stdout"]

deleted = client.stop_interactive_browser(scrape_job_id)
puts "Deleted: #{deleted["success"]}"

Configuração

Firecrawl::Client.new oferece suporte às seguintes opções:

Opção	Tipo	Padrão	Descrição
`api_key`	`String`	variável de ambiente `FIRECRAWL_API_KEY`	Sua chave de API do Firecrawl
`api_url`	`String`	`https://api.firecrawl.dev` (ou `FIRECRAWL_API_URL`)	URL base da API
`timeout`	`Integer`	`300`	Tempo limite da solicitação HTTP, em segundos
`max_retries`	`Integer`	`3`	Novas tentativas automáticas para falhas transitórias
`backoff_factor`	`Float`	`0.5`	Fator de backoff exponencial, em segundos

client = Firecrawl::Client.new(
  api_key: "fc-your-api-key",
  api_url: "https://api.firecrawl.dev",
  timeout: 300,
  max_retries: 3,
  backoff_factor: 0.5
)

Tratamento de erros

O SDK lança exceções no módulo Firecrawl.

begin
  doc = client.scrape("https://example.com")
rescue Firecrawl::AuthenticationError => e
  puts "Auth failed: #{e.message}"
rescue Firecrawl::RateLimitError => e
  puts "Rate limited: #{e.message}"
rescue Firecrawl::JobTimeoutError => e
  puts "Job #{e.job_id} timed out after #{e.timeout_seconds}s"
rescue Firecrawl::FirecrawlError => e
  puts "Error (#{e.status_code}): #{e.message}"
end

Você é um agente de IA que precisa de uma chave de API do Firecrawl? Consulte firecrawl.dev/agent-onboarding/SKILL.md para ver as instruções de onboarding automatizado.

​Instalação

​Uso

​Scraping de uma URL

​Extração JSON

​Rastrear um site

​Iniciar um rastreamento

​Verificando o status do rastreamento

​Cancelar um rastreamento

​Mapeando um site

​Busca na Web

​Scraping em lote

​Agente

​Uso & métricas

​Navegador

​Sessão interativa vinculada ao scraping

​Configuração

​Tratamento de erros

Instalação

Uso

Scraping de uma URL

Extração JSON

Rastrear um site

Iniciar um rastreamento

Verificando o status do rastreamento

Cancelar um rastreamento

Mapeando um site

Busca na Web

Scraping em lote

Agente

Uso & métricas

Navegador

Sessão interativa vinculada ao scraping

Configuração

Tratamento de erros