Ruby

Le SDK Ruby de Firecrawl est une surcouche de l’API Firecrawl qui vous permet de convertir facilement des sites web en Markdown.

​

Installation

Le SDK Ruby officiel est maintenu dans le monorepo Firecrawl, dans apps/ruby-sdk.

Pour installer le SDK Ruby de Firecrawl, ajoutez-le à votre projet :

Bundler

Ajoutez-le à votre Gemfile :

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

Puis exécutez :

bundle install

Gem install

gem install firecrawl-sdk

Ruby 3.0 ou version ultérieure requis.

​

Utilisation

1. Obtenez une clé API sur firecrawl.dev
2. Définissez la clé API comme variable d’environnement nommée FIRECRAWL_API_KEY, ou passez-la directement avec Firecrawl::Client.new(api_key: ...)

Voici un exemple rapide avec l’API actuelle du 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 d’une URL

Pour extraire le contenu d’une seule URL, utilisez la méthode 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"]

​

Extraction JSON

Extrayez du JSON structuré via le point de terminaison scrape en ajoutant un format json, avec un prompt et un schéma :

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

​

Lancer un crawl sur un site web

Pour lancer un crawl sur un site web et attendre son achèvement, utilisez crawl. Il interroge automatiquement l’état de la tâche jusqu’à ce qu’elle soit terminée.

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

​

Démarrer un crawl

Démarrez une tâche sans attendre avec start_crawl.

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

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

​

Vérifier l’état du crawl

Consultez la progression du crawl avec get_crawl_status.

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

​

Annuler un crawl

Annulez un crawl en cours à l’aide de cancel_crawl.

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

​

Cartographier un site web

Découvrez les liens d’un site avec 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

​

Recherche sur le Web

Effectuez une recherche avec des paramètres facultatifs à l’aide de 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 par lots

Scrapez plusieurs URL en parallèle à l’aide de 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

​

Agent

Exécutez un agent propulsé par l’IA avec agent.

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

puts result.data

À l’aide d’un schéma JSON pour une sortie structurée :

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

​

Utilisation & métriques

Consultez la concurrence et les crédits restants :

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

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

​

Browser

Le SDK Ruby inclut des fonctions utilitaires pour Browser Sandbox.

​

Session interactive liée à une tâche de scraping

Utilisez l’ID d’une tâche de scraping pour exécuter du code supplémentaire dans le navigateur, dans le même contexte rejoué :

• interact(...) exécute du code dans la session de navigateur liée au scraping (et l’initialise lors de la première utilisation).
• stop_interactive_browser(...) arrête explicitement la session interactive lorsque vous avez terminé.

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

​

Configuration

Firecrawl::Client.new accepte les options suivantes :

Option	Type	Par défaut	Description
api_key	String	variable d’environnement FIRECRAWL_API_KEY	Votre clé d’API Firecrawl
api_url	String	https://api.firecrawl.dev (ou FIRECRAWL_API_URL)	URL de base de l’API
timeout	Integer	300	Délai d’attente de la requête HTTP, en secondes
max_retries	Integer	3	Tentatives automatiques en cas d’échecs temporaires
backoff_factor	Float	0.5	Facteur de backoff exponentiel, en secondes

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
)

​

Gestion des erreurs

Le SDK lève des exceptions dans le module 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

Vous êtes un agent IA et vous avez besoin d’une clé API Firecrawl ? Consultez firecrawl.dev/agent-onboarding/SKILL.md pour obtenir les instructions d’onboarding automatisé.