SDK de Ruby | Firecrawl

Instalación

El SDK oficial de Ruby se mantiene en el monorepo de Firecrawl, en apps/ruby-sdk. Para instalar el SDK de Ruby de Firecrawl, añádelo a tu proyecto:

Bundler
Gem install

Añádelo a tu Gemfile:

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

Luego, ejecuta:

bundle install

gem install firecrawl-sdk

Requiere Ruby 3.0 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 con Firecrawl::Client.new(api_key: ...)

Aquí tienes un ejemplo rápido con la API actual del 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}"

Hacer scraping de una URL

Para hacer scraping de una sola URL, usa el 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"]

Extracción JSON

Extrae JSON estructurado a través del endpoint scrape incluyendo el formato json junto con un prompt y un 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

Rastreo de un sitio web

Para rastrear un sitio web y esperar a que finalice, usa crawl. Realiza sondeos automáticamente hasta que el trabajo termine.

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 un rastreo

Inicia un trabajo sin esperar con start_crawl.

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

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

Consultar el estado del rastreo

Consulta el progreso del rastreo con get_crawl_status.

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

Cancelar un rastreo

Cancela un rastreo en curso con cancel_crawl.

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

Mapeo de un sitio web

Descubre enlaces en un sitio web utilizando 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

Buscar en la Web

Busca con opciones de configuración opcionales utilizando 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 por lotes

Realiza scraping de varias URL en paralelo con 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

Ejecuta un agente con IA mediante agent.

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

puts result.data

Con un esquema JSON para salida estructurada:

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

Consulta la concurrencia y los 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}"

Browser

El SDK de Ruby incluye utilidades para el sandbox del navegador.

Sesión interactiva vinculada al scraping

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

interact(...) ejecuta código en la sesión de browser vinculada al scraping (y la inicializa la primera vez que se usa).
stop_interactive_browser(...) detiene explícitamente la sesión interactiva cuando terminas.

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"]}"

Configuración

Firecrawl::Client.new admite las siguientes opciones:

Opción	Tipo	Predeterminado	Descripción
`api_key`	`String`	variable de entorno `FIRECRAWL_API_KEY`	Tu clave de la API de Firecrawl
`api_url`	`String`	`https://api.firecrawl.dev` (o `FIRECRAWL_API_URL`)	URL base de la API
`timeout`	`Integer`	`300`	Tiempo de espera de la solicitud HTTP en segundos
`max_retries`	`Integer`	`3`	Reintentos automáticos ante fallos transitorios
`backoff_factor`	`Float`	`0.5`	Factor de backoff exponencial en 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
)

Manejo de errores

El SDK lanza excepciones dentro del 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

¿Eres un agente de IA que necesita una clave de API de Firecrawl? Consulta firecrawl.dev/agent-onboarding/SKILL.md para ver las instrucciones de incorporación automática.

General

Oficial

Ruby

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

Mapeo de un sitio web

Buscar en la Web

Scraping por lotes

Agente

Uso & métricas

Browser

Sesión interactiva vinculada al scraping

Configuración

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

​Mapeo de un sitio web

​Buscar en la Web

​Scraping por lotes

​Agente

​Uso & métricas

​Browser

​Sesión interactiva vinculada al scraping

​Configuración

​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

Mapeo de un sitio web

Buscar en la Web

Scraping por lotes

Agente

Uso & métricas

Browser

Sesión interactiva vinculada al scraping

Configuración

Manejo de errores