Skip to main content
Firecrawl Docs

Modo JSON - Resultado Estruturado

Extraia dados estruturados de páginas com LLMs
5 min read

Escolha da ferramenta certa. O modo JSON (esta página) é ideal quando você tem uma URL e quer extrair campos dessa única página.

  • Para qualquer caso além de uma única URL — várias URLs, padrões de URL ou descoberta orientada por agentes — consulte Agent.
  • Comparação completa: Como escolher o Extrator de Dados.
Note

Mudança na API v2: A extração de schema JSON é totalmente suportada na v2, mas o formato da API mudou. Na v2, o esquema é incorporado diretamente no objeto de formatos como formats: [{type: "json", schema: {...}}]. O parâmetro jsonOptions da v1 não existe mais na v2.

Note
Para falhas na validação de esquema e outros erros de extração, consulte Erros — problemas específicos de extração normalmente aparecem como respostas 400 ou 422.

Raspe e extraia dados estruturados com o Firecrawl#

O Firecrawl usa IA para obter dados estruturados de páginas da web em 3 etapas:

  1. Defina o esquema (opcional): Defina um esquema JSON (no formato da OpenAI) para especificar os dados desejados, ou forneça apenas um prompt se não precisar de um esquema rígido, junto com a URL da página.

  2. Faça a requisição: Envie sua URL e o esquema para nosso endpoint /scrape usando o modo JSON. Veja como aqui: Scrape Endpoint Documentation

  3. Obtenha seus dados: Receba dados limpos e estruturados que correspondem ao seu esquema, prontos para uso imediato.

Isso torna rápido e fácil obter dados da web no formato de que você precisa.

Extraia dados estruturados#

Modo JSON via /scrape#

Usado para extrair dados estruturados de páginas extraídas.

Saída:

JSON

Dados estruturados sem esquema#

Você também pode extrair sem um esquema, apenas passando um prompt para o endpoint. O LLM escolhe a estrutura dos dados.

Resultado:

JSON

Exemplo real: extraindo informações de empresas#

Aqui está um exemplo completo de extração de informações estruturadas de empresas a partir de um site:

Resultado:

Output

Opções do formato JSON#

Ao usar o modo JSON na v2, inclua um objeto em formats com o esquema incorporado diretamente:

formats: [{ type: 'json', schema: { ... }, prompt: '...' }]

Parâmetros:

  • schema: schema JSON que descreve a saída estruturada desejada (obrigatório para extração baseada em esquema).
  • prompt: prompt opcional para orientar a extração (também usado para extração sem esquema).
  • checkPromptInjection: booleano opcional (o padrão é false). Quando ativado, o Firecrawl verifica o conteúdo da página extraída em busca de tentativas de injeção de prompt antes de executar a extração. Consulte Detecção de injeção de prompt.

Importante: Diferente da v1, não há um parâmetro separado jsonOptions na v2. O esquema deve ser incluído diretamente dentro do objeto de formato no array formats.

Detecção de injeção de prompt#

Páginas web podem conter texto oculto criado para sequestrar extrações baseadas em LLM — por exemplo, instruções que dizem ao modelo para ignorar seu esquema e retornar dados controlados por um invasor. Se você extrair dados de URLs não confiáveis ou enviadas por usuários, poderá ativar uma proteção opcional que verifica o conteúdo extraído antes de executar a extração:

Como funciona:

  • Uma chamada dedicada ao classificador inspeciona o conteúdo da página extraída (ela é executada em paralelo com a extração, portanto, ativá-la não torna scrapings sem problemas mais lentos).
  • Se uma tentativa de injeção de prompt for detectada, a solicitação falhará com um HTTP 403 e o código de erro SCRAPE_PROMPT_INJECTION_DETECTED — nenhum resultado da extração será retornado.
  • A verificação é cobrada como +4 créditos além do custo padrão do formato JSON quando é executada. Se o scraping falhar após a execução da verificação (inclusive quando uma injeção é detectada e a solicitação é bloqueada), serão cobrados 5 créditos em vez dos 0 habituais para um scraping com falha, pois a chamada ao classificador ainda foi executada.

Na v1, a mesma opção está disponível como jsonOptions.checkPromptInjection. Ela também é exposta em todos os SDKs oficiais (por exemplo, checkPromptInjection no SDK JS, check_prompt_injection no formato JSON v2 do SDK Python's).

Note

Atributos HTML não estão disponíveis na extração JSON. A extração JSON funciona a partir da conversão da página para markdown, que preserva apenas o conteúdo de texto visível. Atributos HTML (por exemplo, data-id, atributos personalizados em elementos) são removidos durante a conversão e o LLM não consegue vê-los. Se você precisar extrair valores de atributos HTML, use o formato rawHtml e faça o parsing dos atributos no lado do cliente, ou use uma ação executeJavascript para injetar os valores dos atributos em texto visível antes da extração.

Dicas para extração consistente#

Se você estiver obtendo resultados inconsistentes ou incompletos na extração JSON, estas práticas podem ajudar:

  • Mantenha os prompts curtos e focados. Prompts longos com muitas regras aumentam a variabilidade. Em vez disso, mova restrições específicas (como valores permitidos) para o esquema.
  • Use nomes de propriedades concisos. Evite incluir instruções ou listas de enum nos nomes das propriedades. Use uma chave curta como "installation_type" e coloque os valores permitidos em um array enum.
  • Adicione arrays enum para campos com valores restritos. Quando um campo tiver um conjunto fixo de valores, liste-os em enum e garanta que correspondam exatamente ao texto exibido na página.
  • Inclua tratamento de null nas descrições dos campos. Adicione "Return null if not found on the page." à description de cada campo para que o modelo não tente deduzir valores ausentes.
  • Adicione dicas de localização. Diga ao modelo onde encontrar os dados na página, por exemplo: "Flow rate in GPM from the Specifications table.".
  • Divida esquemas grandes em solicitações menores. Esquemas com muitos campos (por exemplo, 30+) produzem resultados menos consistentes. Divida-os em 2–3 solicitações de 10–15 campos cada.
  • Evite minItems/maxItems em arrays. Palavras-chave de validação do esquema JSON como minItems e maxItems não controlam a quantidade de conteúdo que o scraper coleta. Definir minItems: 20 não fará o LLM retornar mais itens — em vez disso, ele pode alucinar entradas para satisfazer a restrição. Remova essas palavras-chave e use um prompt no lugar (por exemplo, "Extract ALL reviews from the page. Do not skip any.") para orientar a completude.
  • Use "type": "array" para extrair listas de itens. Se você precisar extrair vários itens (por exemplo, uma lista de pessoas, produtos ou avaliações), agrupe-os em uma propriedade do tipo array com um bloco items. Usar "type": "object" para uma lista retornará apenas um único item. Veja o exemplo de esquema de array abaixo.

Exemplo de um esquema bem estruturado:

Exemplo de como extrair uma lista de itens:

Quando uma página contém vários itens (por exemplo, membros da equipe, produtos ou avaliações), use "type": "array" com "items" para obter a lista completa:

Você é um agente de IA que precisa de uma chave de API do Firecrawl? Veja firecrawl.dev/agent-onboarding/SKILL.md para ver instruções de onboarding automatizado.

Raspagem em loteRastreio de mudanças