Guia Avançado de Scraping

Referência para todas as opções em todos os endpoints de scraping, rastreamento, mapeamento e agente do Firecrawl."

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

# pip install firecrawl-pyfrom firecrawl import Firecrawlfirecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")doc = firecrawl.scrape("https://firecrawl.dev")print(doc.markdown)

O Firecrawl oferece suporte a PDFs. Use a opção parsers (por exemplo, parsers: ["pdf"]) quando quiser garantir a extração de PDFs. Você pode controlar a estratégia de extração com a opção mode:

• auto (padrão) — tenta primeiro uma extração rápida baseada em texto e, se necessário, recorre a OCR.
• fast — apenas extração baseada em texto (texto embutido). Mais rápido, mas ignora páginas digitalizadas ou com muitas imagens.
• ocr — força a extração via OCR em todas as páginas. Use para documentos digitalizados ou quando auto classificar uma página incorretamente.

{ type: "pdf" } e "pdf" usam por padrão mode: "auto".

"parsers": [{ "type": "pdf", "mode": "fast", "maxPages": 50 }]

Ao usar o endpoint /scrape, você pode personalizar a requisição com as seguintes opções.

O array formats controla quais tipos de saída o scraper retorna. Padrão: ["markdown"].

Formatos em string: passe o nome diretamente (por exemplo, "markdown").

Formatos em objeto: passe um objeto com type e opções adicionais.

Defina mobile: true para emular um dispositivo móvel. Isso é útil quando um site responsivo oculta conteúdo na versão desktop ou exibe um layout diferente em navegadores móveis.

Para sites específicos de uma região, combine com location e uma captura de tela em um dispositivo móvel para verificar o layout renderizado:

from firecrawl import Firecrawlfirecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")doc = firecrawl.scrape(    "https://example.com",    mobile=True,    location={"country": "GB", "languages": ["en-GB"]},    formats=[        "markdown",        {"type": "screenshot", "fullPage": True, "viewport": {"width": 390, "height": 844}},    ],    only_main_content=False,    wait_for=2000,)print(doc.markdown)

Se o site ainda exibir um layout para desktop apesar de mobile: true, adicione um User-Agent mobile via headers:

{  "headers": {    "User-Agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Mobile/15E148 Safari/604.1"  }}

Esses parâmetros controlam quais partes da página aparecem na saída. Quando onlyMainContent é true (o padrão), o boilerplate (nav, footer etc.) é removido. includeTags e excludeTags são aplicados ao DOM original da página, não ao resultado após a filtragem, portanto seus seletores devem segmentar os elementos conforme aparecem no HTML de origem. Defina onlyMainContent: false para usar a página completa como ponto de partida para a filtragem por tags.

{ "type": "pdf", "mode": "fast" | "auto" | "ocr", "maxPages": 10, "pages": true, "blocks": true, "pageMarkers": true }

Execute ações no navegador antes do scraping. Isso é útil para conteúdo dinâmico, navegação ou páginas com acesso restrito. Você pode incluir até 50 ações por requisição, e o tempo total de espera entre todas as ações wait e waitFor não pode exceder 60 segundos.

from firecrawl import Firecrawlfirecrawl = 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)

• Write requer um click anterior para focar o elemento de destino.
• Scroll aceita um selector opcional para rolar um elemento específico em vez da página.
• Wait aceita milliseconds (atraso fixo) ou selector (esperar até que fique visível).
• As ações são executadas sequencialmente: cada etapa é concluída antes da próxima começar.
• Ações não são compatíveis com PDFs. Se a URL for resolvida para um PDF, a requisição falhará.

Fazendo uma captura de tela:

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

Executar JavaScript (por exemplo, para extrair dados embutidos na página):

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": "executeJavascript", "script": "document.querySelector(\"#__NEXT_DATA__\").textContent" }    ],    "formats": ["markdown"]  }'

O valor de retorno de cada ação executeJavascript é armazenado no array actions.javascriptReturns da resposta.

A solicitação abaixo combina várias opções de scraping:

curl -X POST https://api.firecrawl.dev/v2/scrape \    -H 'Content-Type: application/json' \    -H 'Authorization: Bearer fc-YOUR-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"]    }'

Essa requisição retorna markdown, HTML, HTML bruto, links e uma captura de tela da página inteira. Ela restringe o conteúdo a <h1>, <p>, <a> e .main-content, enquanto exclui #ad e #footer, aguarda 1 segundo antes de iniciar o scraping, define um tempo limite de 15 segundos e habilita a análise de PDFs.

Consulte a referência completa da API de Scrape para mais detalhes.

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

from firecrawl import Firecrawlfirecrawl = Firecrawl(api_key='fc-YOUR-API-KEY')doc = firecrawl.scrape('https://firecrawl.dev', {  'formats': [{    'type': 'json',    'prompt': 'Extract the features of the product',    'schema': {      'type': 'object',      'properties': { 'features': { 'type': 'object' } },      'required': ['features']    }  }]})print(doc.json)

Use o endpoint /v2/agent para extração autônoma de dados em várias páginas. O agente é executado de forma assíncrona: você inicia um job e depois consulta os resultados.

Agent é a referência canônica para este endpoint, incluindo rastros de execução, webhooks e a lista completa de parâmetros.

from firecrawl import Firecrawlfirecrawl = Firecrawl(api_key='fc-YOUR-API-KEY')# Iniciar job do agentestarted = firecrawl.start_agent(    prompt="Extraia o título e a descrição",    urls=["https://docs.firecrawl.dev"],    schema={"type": "object", "properties": {"title": {"type": "string"}, "description": {"type": "string"}}, "required": ["title"]})# Consultar statusstatus = firecrawl.get_agent_status(started["id"])print(status.get("status"), status.get("data"))

Faça requisições periódicas para GET /v2/agent/{jobId} para verificar o progresso. O campo status da resposta será "processing", "completed" ou "failed".

curl -X GET https://api.firecrawl.dev/v2/agent/YOUR-JOB-ID \  -H 'Authorization: Bearer fc-YOUR-API-KEY'

Os SDKs de Python e Node também fornecem um método conveniente (firecrawl.agent()) que inicia o job e consulta o status automaticamente até a conclusão.

Para rastrear várias páginas, use o endpoint /v2/crawl. O rastreamento é executado de forma assíncrona e retorna um ID do job. Use o parâmetro limit para controlar quantas páginas serão rastreadas. Se omitido, o rastreamento processará até 10.000 páginas.

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",      "limit": 10    }'

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

Use o ID do job para verificar o status do rastreamento e recuperar os resultados.

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

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

Você pode fornecer um prompt em linguagem natural para que o Firecrawl defina as configurações de rastreamento. Visualize-as primeiro:

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": "Extract docs and blog"  }'

Ao usar o endpoint /v2/crawl, você pode configurar o comportamento do crawler com as seguintes opções.

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    }'

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

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

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

• User Agent: permita FirecrawlAgent no seu firewall ou nas suas regras de segurança.
• Endereços IP: o Firecrawl não usa um conjunto fixo de IPs de saída.

Se o seu firewall bloquear requisições de saída da sua aplicação para serviços externos, você precisa adicionar o endereço IP do servidor da API do Firecrawl à lista de permissões para que sua aplicação possa acessar a API do Firecrawl (api.firecrawl.dev):

• Endereço IP: 35.245.250.27

Adicione esse IP à lista de permissões de saída do seu firewall para que seu backend possa enviar requisições de scrape, crawl, map e agent para o Firecrawl.