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", "images"]
Formatos de objeto:
- JSON: { type: "json", prompt, schema }
- Captura de tela: { type: "screenshot", fullPage?, quality?, viewport? }
- Rastreio de mudanças: { 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 preparo da página (`waitFor`)

Tipo: integer
Descrição: Tempo extra de espera, em milissegundos, antes do scraping (use com moderação). Esse tempo de espera é adicional ao recurso de espera inteligente do Firecrawl.
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"].

Actions (`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 é particularmente útil para interagir com conteúdo dinâmico, navegar entre páginas ou acessar conteúdo que requer interação do usuário.

Tipo: array
Descrição: Sequência de etapas do navegador a serem executadas antes do scraping.
Ações suportadas:
- wait - Aguarda o carregamento da página: { type: "wait", milliseconds: number } ou { type: "wait", selector: string }
- click - Clica em um elemento: { type: "click", selector: string, all?: boolean }
- write - Digita texto em um campo: { type: "write", text: string } (o elemento deve ser focado antes com click)
- press - Pressiona uma tecla do teclado: { type: "press", key: string }
- scroll - Rola a página: { type: "scroll", direction: "up" | "down", selector?: string }
- screenshot - Captura uma captura de tela: { type: "screenshot", fullPage?: boolean, quality?: number, viewport?: { width: number, height: number } }
- scrape - Faz scrape de um subelemento da página: { type: "scrape" }
- executeJavascript - Executa código JS: { type: "executeJavascript", script: string }
- pdf - Gera um PDF: { type: "pdf", format?: string, landscape?: boolean, scale?: number }

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': 'click', 'selector': '#q' },
    { 'type': 'write', 'text': 'firecrawl' },
    { 'type': 'press', 'key': 'Enter' },
    { 'type': 'wait', 'milliseconds': 2000 }
  ],
  'formats': ['markdown']
})

print(doc.markdown)

Notas sobre a execução de ações

Write action: Você deve primeiro colocar o foco no elemento usando uma ação de click antes de usar write. O texto é digitado caractere por caractere para simular a entrada pelo teclado.
Scroll selector: Se você quiser rolar um elemento específico em vez da página inteira, forneça o parâmetro selector para scroll.
Wait with selector: Você pode esperar até que um elemento específico esteja visível usando wait com um parâmetro selector, ou esperar por uma duração fixa usando milliseconds.
Actions are sequential: As ações são executadas em ordem, e o Firecrawl espera que as interações da página sejam concluídas antes de passar para a próxima ação.

Exemplos de Ações Avançadas

Capturando a tela:

cURL

curl -X POST https://api.firecrawl.dev/v2/scrape \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer fc-YOUR-API-KEY' \
  -d '{
    "url": "https://example.com",
    "actions": [
      { "type": "click", "selector": "#load-more" },
      { "type": "wait", "milliseconds": 1000 },
      { "type": "screenshot", "fullPage": true, "quality": 80 }
    ]
  }'

Clicar em vários elementos:

cURL

curl -X POST https://api.firecrawl.dev/v2/scrape \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer fc-YOUR-API-KEY' \
  -d '{
    "url": "https://example.com",
    "actions": [
      { "type": "click", "selector": ".expand-button", "all": true },
      { "type": "wait", "milliseconds": 500 }
    ],
    "formats": ["markdown"]
  }'

Gerar um PDF:

cURL

curl -X POST https://api.firecrawl.dev/v2/scrape \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer fc-YOUR-API-KEY' \
  -d '{
    "url": "https://example.com",
    "actions": [
      { "type": "pdf", "format": "A4", "landscape": false }
    ]
  }'

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 de JSON via formatos

Use o objeto de formato JSON em formats para extrair dados estruturados em uma única chamada:

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": "Extract the features of the product",
      "schema": {"type": "object", "properties": {"features": {"type": "object"}}, "required": ["features"]}
    }]
  }'

Endpoint de extração

Use a API dedicada de jobs de extração quando quiser 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: 'Extract title',
  schema: { type: 'object', properties: { title: { type: 'string' } }, required: ['title'] }
});

// Verificar 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 crawl

Usado para verificar o status de um job de crawl e obter o resultado.

cURL

curl -X GET https://api.firecrawl.dev/v2/crawl/1234-5678-9101 \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer fc-YOUR-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 poderá incluir um 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 configurar o comportamento do crawler 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
    }'

Mapeamento de links de sites

O endpoint /v2/map identifica URLs relacionadas a um determinado site.

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 mapeamento

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!

Introdução

Novidades

Funcionalidades principais

Webhooks

Guias para desenvolvedores

Casos de uso

Como contribuir

​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 preparo da página (waitFor)

​Atualidade e cache (maxAge)

​Tempo de requisição (timeout)

​Processamento de PDF (parsers)

​Actions (actions)

​Notas sobre a execução de ações

​Exemplos de Ações Avançadas

​Exemplo de uso

​Extração de JSON via formatos

​Endpoint de extração

​Rastreando várias páginas

​Verificar job de crawl

​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

​Mapeamento de links de sites

​Uso

​Opções de mapeamento

​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 preparo da página (`waitFor`)

Atualidade e cache (`maxAge`)

Tempo de requisição (`timeout`)

Processamento de PDF (`parsers`)

Actions (`actions`)

Notas sobre a execução de ações

Exemplos de Ações Avançadas

Exemplo de uso

Extração de JSON via formatos

Endpoint de extração

Rastreando várias páginas

Verificar job de crawl

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

Mapeamento de links de sites

Uso

Opções de mapeamento

search

limit

sitemap

includeSubdomains