Firecrawl

Firecrawl is a lightweight Ruby gem that provides a semantically straightfoward interface to the Firecrawl.dev API, allowing you to easily scrape web content, take screenshots, as well as crawl entire web domains.

The gem is particularly useful when working with Large Language Models (LLMs) as it can provide markdown information for real time information lookup as well as grounding.

require 'firecrawl'

Firecrawl.api_key ENV[ 'FIRECRAWL_API_KEY' ]
response = Firecrawl.scrape( 'https://example.com' )
if response.success?
  result = response.result 
  puts result.metadata[ 'title' ]
  puts '---'
  puts result.markdown
  puts "Screenshot URL: #{ result.screenshot_url }"
else 
  puts response.result.error_description 
end 

Installation

Add this line to your application's Gemfile:

gem 'firecrawl'

Then execute:

$ bundle install

Or install it directly:

$ gem install firecrawl

Usage

Scraping

The simplest way to use Firecrawl is to scrape, which will scrape the content of a single page at the given url and optionally convert it to markdown as well as create a screenshot. You can chose to scrape the entire page or only the main content.

Firecrawl.api_key ENV[ 'FIRECRAWL_API_KEY' ]
response = Firecrawl.scrape( 'https://example.com', format: :markdown )

if response.success?
  result = response.result
  if result.success?
    puts result.metadata[ 'title' ]
    puts result.markdown
  end
else
  puts response.result.error_description
end

In this basic example we have globally set the Firecrawl.api_key from the environment and then used the Firecrawl.scrape convenience method to make a request to the Firecrawl API to scrape the https://example.com page and return markdown ( markdown and the main content of the page are returned by default so we could have ommitted the options entirelly ).

The Firecrawl.scrape method instantiates a Firecrawl::ScrapeRequest instance and then calls it's submit method. The following is the equivalent code which makes explict use of the Firecrawl::ScrapeRequest class.

request = Firecrawl::ScrapeRequest.new( api_key: ENV[ 'FIRECRAWL_API_KEY' ] )
response = request.submit( 'https://example.com', format: markdown )

if response.success?
  result = response.result
  if result.success?
    puts result.metadata[ 'title' ]
    puts result.markdown
  end
else
  puts response.result.error_description
end

Notice also that in this example we've directly passed the api_key to the individual request. This is optional. If you set the key globally and omit it in the request constructor the ScrapeRequest instance will use the globally assigned api_key.

Scrape Options

You can customize scraping behavior using options, either by passing an option hash to submit method, as we have done above, or by building a ScrapeOptions instance:

options = Firecrawl::ScrapeOptions.build do 
  formats           [ :html, :markdown, :screenshot ]
  only_main_content true
  include_tags      [ 'article', 'main' ]
  exclude_tags      [ 'nav', 'footer' ]
  wait_for          5000  # milliseconds
end

request = Firecrawl::ScrapeRequest.new( api_key: ENV[ 'FIRECRAWL_API_KEY' ] )
response = request.submit( 'https://example.com', options )

Scrape Response

The Firecrawl gem is based on the Faraday gem, which permits you to customize the request orchestration, up to and including changing the actual HTTP implementation used to make the request. See Connections below for additional details.

Any Firecrawl request, including the submit method as used above, will thus return a Faraday::Response. This response includes a success? method which indicates if the request was successful. If the request was successful, the response.result method will be an instance of Firecrawl::ScrapeResult that will encapsulate the scraping result. This instance, in turn, has a success? method which will return true if Firecrawl successfully scraped the page.

A successful result will include html, markdown, screenshot, as well as any action and llm results and related metadata.

If the response is not successful ( if response.success? is false ) then response.result will be an instance of Firecrawl::ErrorResult which will provide additional details about the nature of the failure.

Batch Scraping

For scraping multiple URLs efficiently:

request = Firecrawl::BatchScrapeRequest.new( api_key: ENV[ 'FIRECRAWL_API_KEY' ] )

urls = [ 'https://example.com', 'https://example.org' ]
options = Firecrawl::ScrapeOptions.build do 
  format :markdown
  only_main_content true
end

response = request.submit( urls, options )
while response.success?
  batch_result = response.result
  batch_result.scrape_results.each do |result|
    puts result.metadata['title']
    puts result.markdown
    puts "\n---\n"
  end
  break unless batch_result.status?( :scraping )
  sleep 0.5
  response = request.retrieve( batch_result )
end

Site Mapping

To retrieve a site's structure:

request = Firecrawl::MapRequest.new( api_key: ENV[ 'FIRECRAWL_API_KEY' ] )

options = Firecrawl::MapOptions.build do 
  limit 100
  ignore_subdomains true
end

response = request.submit( 'https://example.com', options )
if response.success?
  result = response.result
  result.links.each do |link|
    puts link
  end
end

Site Crawling

For comprehensive site crawling:

request = Firecrawl::CrawlRequest.new( api_key: ENV[ 'FIRECRAWL_API_KEY' ] )

options = Firecrawl::CrawlOptions.build do 
  maximum_depth 2
  limit 10
  scrape_options do 
    format :markdown
    only_main_content true
  end
end

response = request.submit( 'https://example.com', options )
while response.success?
  crawl_result = response.result
  crawl_result.scrape_results.each do | result |
    puts result.metadata[ 'title' ]
    puts result.markdown
  end
  break unless crawl_result.status?( :scraping )
  sleep 0.5
  response = request.retrieve( crawl_result )
end

Response Structure

All Firecrawl requests return a Faraday response with an added result method. The result will be one of:

• ScrapeResult: Contains the scraped content and metadata
• BatchScrapeResult: Contains multiple scrape results
• MapResult: Contains discovered links
• CrawlResult: Contains scrape results from crawled pages
• ErrorResult: Contains error information if the request failed

Working with Results

response = request.submit(url, options)
if response.success?
  result = response.result
  if result.success?
    # Access scraped content
    puts result.metadata['title']
    puts result.markdown
    puts result.html
    puts result.raw_html
    puts result.screenshot_url
    puts result.links
    
    # Check for warnings
    puts result.warning if result.warning
  end
else
  error = response.result
  puts "#{error.error_type}: #{error.error_description}"
end

License

The gem is available as open source under the terms of the MIT License.