Guia Avançado de Scraping

Este guia apresenta os diferentes endpoints do Firecrawl e como utilizá-los ao máximo, com todos os seus parâmetros.

Raspagem básica com o Firecrawl

Para raspar uma única página e obter conteúdo em Markdown limpo, use o endpoint /scrape.

# pip install firecrawl-py

from firecrawl import Firecrawl

firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")

doc = firecrawl.scrape("https://firecrawl.dev")

print(doc.markdown)

Extração de PDFs

O Firecrawl oferece suporte a PDFs. Use a opção parsers (por exemplo, parsers: ["pdf"]) quando quiser garantir a extração de PDFs.

Opções de scraping

Ao usar o endpoint /scrape, você pode personalizar a coleta com as opções abaixo.

Formatos (`formats`)

Tipo: array
Strings: ["markdown", "links", "html", "rawHtml", "summary"]
Formatos de objeto:
- JSON: { type: "json", prompt, schema }
- Captura de tela: { type: "screenshot", fullPage?, quality?, viewport? }
- Rastreamento de alterações: { type: "changeTracking", modes?, prompt?, schema?, tag? } (requer markdown)
Padrão: ["markdown"]

Conteúdo da página inteira vs conteúdo principal (`onlyMainContent`)

Type: boolean
Description: Por padrão, o scraper retorna apenas o conteúdo principal. Defina como false para retornar o conteúdo da página inteira.
Default: true

Incluir tags (`includeTags`)

Tipo: array
Descrição: Tags/classes/IDs HTML a serem incluídas na extração.

Excluir tags (`excludeTags`)

Tipo: array
Descrição: Tags/classes/IDs HTML a serem excluídos da extração.

Aguardar a página ficar pronta (`waitFor`)

Tipo: integer
Descrição: Milissegundos para esperar antes de fazer o scraping (use com moderação).
Padrão: 0

Atualidade e cache (`maxAge`)

Tipo: integer (milissegundos)
Descrição: Se houver uma versão em cache da página mais recente do que maxAge, o Firecrawl a retorna imediatamente; caso contrário, faz uma nova raspagem e atualiza o cache. Defina 0 para sempre buscar conteúdo novo.
Padrão: 172800000 (2 dias)

Tempo de requisição (`timeout`)

Tipo: integer
Descrição: Duração máxima, em milissegundos, antes de abortar.
Padrão: 30000 (30 segundos)

Processamento de PDF (`parsers`)

Tipo: array
Descrição: Controla o comportamento de processamento. Para processar PDFs, defina parsers: ["pdf"].

Ações (`actions`)

Ao usar o endpoint /scrape, o Firecrawl permite executar várias ações em uma página da web antes de extrair seu conteúdo. Isso é especialmente útil para interagir com conteúdo dinâmico, navegar entre páginas ou acessar conteúdo que exige interação do usuário.

Tipo: array
Descrição: Sequência de etapas do navegador a serem executadas antes da extração.
Ações compatíveis:
- wait { milliseconds }
- click { selector }
- write { selector, text }
- press { key }
- scroll { direction: "up" | "down" }
- scrape { selector } (extrair um subelemento)
- executeJavascript { script }
- pdf (aciona a renderização em PDF em alguns fluxos)

from firecrawl import Firecrawl

firecrawl = Firecrawl(api_key='fc-YOUR-API-KEY')

doc = firecrawl.scrape('https://example.com', {
  actions: [
    { type: 'wait', milliseconds: 1000 },
    { type: 'click', selector: '#accept' },
    { type: 'scroll', direction: 'down' },
    { type: 'write', selector: '#q', text: 'firecrawl' },
    { type: 'press', key: 'Enter' }
  ],
  formats: ['markdown']
})

print(doc.markdown)

Exemplo de uso

cURL

curl -X POST https://api.firecrawl.dev/v2/scrape \
    -H '
    Content-Type: application/json' \
    -H 'Authorization: Bearer fc-SUA-API-KEY' \
    -d '{
      "url": "https://docs.firecrawl.dev",
      "formats": [
        "markdown",
        "links",
        "html",
        "rawHtml",
        { "type": "screenshot", "fullPage": true, "quality": 80 }
      ],
      "includeTags": ["h1", "p", "a", ".main-content"],
      "excludeTags": ["#ad", "#footer"],
      "onlyMainContent": false,
      "waitFor": 1000,
      "timeout": 15000,
      "parsers": ["pdf"]
    }'

Neste exemplo, o scraper vai:

Retornar o conteúdo completo da página em markdown.
Incluir o markdown, o HTML bruto, o HTML, os links e uma captura de tela na resposta.
Incluir apenas as tags HTML <h1>, <p>, <a> e elementos com a classe .main-content, excluindo quaisquer elementos com os IDs #ad e #footer.
Aguardar 1000 milissegundos (1 segundo) antes de iniciar o scraping para permitir o carregamento da página.
Definir a duração máxima da solicitação de scraping em 15000 milissegundos (15 segundos).
Analisar PDFs explicitamente via parsers: ["pdf"].

Aqui está a referência da API: Documentação do endpoint /scrape

Extração em JSON via formatos

Use o objeto de formato JSON em formats para extrair dados estruturados de uma só vez:

curl -X POST https://api.firecrawl.dev/v2/scrape \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer fc-YOUR-API-KEY' \
  -d '{
    "url": "https://firecrawl.dev",
    "formats": [{
      "type": "json",
      "prompt": "Extraia as funcionalidades do produto",
      "schema": {"type": "object", "properties": {"features": {"type": "object"}}, "required": ["features"]}
    }]
  }'

Endpoint /extract

Use a API dedicada de jobs de extração quando precisar de extração assíncrona com verificação de status (polling).

import Firecrawl from '@mendable/firecrawl-js';

const firecrawl = new Firecrawl({ apiKey: 'fc-YOUR-API-KEY' });

// Iniciar job de extração
const started = await firecrawl.startExtract({
  urls: ['https://docs.firecrawl.dev'],
  prompt: 'Extrair título',
  schema: { type: 'object', properties: { title: { type: 'string' } }, required: ['title'] }
});

// Consultar status
const status = await firecrawl.getExtractStatus(started.id);
console.log(status.status, status.data);

Rastreando várias páginas

Para rastrear várias páginas, use o endpoint /v2/crawl.

cURL

curl -X POST https://api.firecrawl.dev/v2/crawl \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer fc-YOUR-API-KEY' \
    -d '{
      "url": "https://docs.firecrawl.dev"
    }'

Retorna um ID

{ "id": "1234-5678-9101" }

Verificar job de rastreamento

Usado para conferir o status de um job de rastreamento e obter seu resultado.

cURL

curl -X GET https://api.firecrawl.dev/v2/crawl/1234-5678-9101 \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer fc-SUA-API-KEY'

Paginação/Próxima URL

Se o conteúdo tiver mais de 10 MB ou se a tarefa de crawl ainda estiver em execução, a resposta pode incluir o parâmetro next, uma URL para a próxima página de resultados.

Prévia do prompt e dos parâmetros de crawl

Você pode fornecer um prompt em linguagem natural para o Firecrawl deduzir as configurações de crawl. Veja a prévia delas primeiro:

cURL

curl -X POST https://api.firecrawl.dev/v2/crawl/params-preview \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer fc-YOUR-API-KEY' \
  -d '{
    "url": "https://docs.firecrawl.dev",
    "prompt": "Extrair documentação e blog"
  }'

Opções do crawler

Ao usar o endpoint /v2/crawl, você pode personalizar o comportamento do rastreamento com:

includePaths

Tipo: array
Descrição: Padrões de regex a incluir.
Exemplo: ["^/blog/.*$", "^/docs/.*$"]

excludePaths

Tipo: array
Descrição: Padrões de regex a serem excluídos.
Exemplo: ["^/admin/.*$", "^/private/.*$"]

maxDiscoveryDepth

Tipo: integer
Descrição: Profundidade máxima de descoberta para encontrar novas URLs.

limit

Type: integer
Description: Número máximo de páginas a rastrear.
Default: 10000

crawlEntireDomain

Tipo: boolean
Descrição: Explora por páginas relacionadas (irmãs/pais) para cobrir todo o domínio.
Padrão: false

allowExternalLinks

Tipo: boolean
Descrição: Segue links para domínios externos.
Padrão: false

allowSubdomains

Tipo: boolean
Descrição: Segue subdomínios do domínio principal.
Padrão: false

delay

Tipo: number
Descrição: Atraso, em segundos, entre as extrações.
Padrão: undefined

scrapeOptions

Tipo: object
Descrição: Opções para o scraper (veja Formatos acima).
Exemplo: { "formats": ["markdown", "links", {"type": "screenshot", "fullPage": true}], "includeTags": ["h1", "p", "a", ".main-content"], "excludeTags": ["#ad", "#footer"], "onlyMainContent": false, "waitFor": 1000, "timeout": 15000}
Padrões: formats: ["markdown"], cache ativado por padrão (maxAge ~ 2 dias)

Exemplo de uso

cURL

curl -X POST https://api.firecrawl.dev/v2/crawl \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer fc-SUA-API-KEY' \
    -d '{
      "url": "https://docs.firecrawl.dev",
      "includePaths": ["^/blog/.*$", "^/docs/.*$"],
      "excludePaths": ["^/admin/.*$", "^/private/.*$"],
      "maxDiscoveryDepth": 2,
      "limit": 1000
    }'

Mapeando links do site

O endpoint /v2/map identifica URLs relacionadas a um site específico.

Uso

cURL

curl -X POST https://api.firecrawl.dev/v2/map \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer fc-SUA-API-KEY' \
    -d '{
      "url": "https://docs.firecrawl.dev"
    }'

Opções de mapa

search

Tipo: string
Descrição: Filtra links que contêm determinado texto.

limit

Tipo: integer
Descrição: Número máximo de links a serem retornados.
Padrão: 100

sitemap

Tipo: "only" | "include" | "skip"
Descrição: Controla o uso do sitemap durante o mapeamento.
Padrão: "include"

includeSubdomains

Tipo: boolean
Descrição: Inclui os subdomínios do site.
Padrão: true

Aqui está a referência da API correspondente: Documentação do endpoint /map Obrigado pela leitura!

Comece

Recursos Padrão

Recursos agênticos

Webhooks

Casos de uso

Contribuição

​Raspagem básica com o Firecrawl

​Extração de PDFs

​Opções de scraping

​Formatos (formats)

​Conteúdo da página inteira vs conteúdo principal (onlyMainContent)

​Incluir tags (includeTags)

​Excluir tags (excludeTags)

​Aguardar a página ficar pronta (waitFor)

​Atualidade e cache (maxAge)

​Tempo de requisição (timeout)

​Processamento de PDF (parsers)

​Ações (actions)

​Exemplo de uso

​Extração em JSON via formatos

​Endpoint /extract

​Rastreando várias páginas

​Verificar job de rastreamento

​Paginação/Próxima URL

​Prévia do prompt e dos parâmetros de crawl

​Opções do crawler

​includePaths

​excludePaths

​maxDiscoveryDepth

​limit

​crawlEntireDomain

​allowExternalLinks

​allowSubdomains

​delay

​scrapeOptions

​Exemplo de uso

​Mapeando links do site

​Uso

​Opções de mapa

​search

​limit

​sitemap

​includeSubdomains

Raspagem básica com o Firecrawl

Extração de PDFs

Opções de scraping

Formatos (`formats`)

Conteúdo da página inteira vs conteúdo principal (`onlyMainContent`)

Incluir tags (`includeTags`)

Excluir tags (`excludeTags`)

Aguardar a página ficar pronta (`waitFor`)

Atualidade e cache (`maxAge`)

Tempo de requisição (`timeout`)

Processamento de PDF (`parsers`)

Ações (`actions`)

Exemplo de uso

Extração em JSON via formatos

Endpoint /extract

Rastreando várias páginas

Verificar job de rastreamento

Paginação/Próxima URL

Prévia do prompt e dos parâmetros de crawl

Opções do crawler

includePaths

excludePaths

maxDiscoveryDepth

limit

crawlEntireDomain

allowExternalLinks

allowSubdomains

delay

scrapeOptions

Exemplo de uso

Mapeando links do site

Uso

Opções de mapa

search

limit

sitemap

includeSubdomains