Modo JSON | Firecrawl

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.

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.

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:

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.
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
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.

from firecrawl import Firecrawl
from pydantic import BaseModel

app = Firecrawl(
  # Nenhuma API key necessária para começar — adicione uma para limites de taxa mais altos:
  # api_key="fc-SUA-CHAVE-API",
)

class CompanyInfo(BaseModel):
    company_mission: str
    supports_sso: bool
    is_open_source: bool
    is_in_yc: bool

result = app.scrape(
    'https://firecrawl.dev',
    formats=[{
      "type": "json",
      "schema": CompanyInfo.model_json_schema()
    }],
    only_main_content=False,
    timeout=120000
)

print(result)

import { Firecrawl } from "firecrawl";
import { z } from "zod";

const app = new Firecrawl({
  // Nenhuma API key necessária para começar — adicione uma para limites de taxa mais altos:
  // apiKey: "fc-YOUR_API_KEY",
});

// Define schema to extract contents into
const schema = z.object({
  company_mission: z.string(),
  supports_sso: z.boolean(),
  is_open_source: z.boolean(),
  is_in_yc: z.boolean()
});

const result = await app.scrape("https://firecrawl.dev", {
  formats: [{
    type: "json",
    schema: schema
  }],
});

console.log(result);

# Nenhuma API key necessária para começar — adicione -H "Authorization: Bearer YOUR_API_KEY" para limites de taxa mais altos:
curl -X POST https://api.firecrawl.dev/v2/scrape \
    -H 'Content-Type: application/json' \
    -d '{
      "url": "https://firecrawl.dev",
      "formats": [ {
        "type": "json",
        "schema": {
          "type": "object",
          "properties": {
            "company_mission": {
                      "type": "string"
            },
            "supports_sso": {
                      "type": "boolean"
            },
            "is_open_source": {
                      "type": "boolean"
            },
            "is_in_yc": {
                      "type": "boolean"
            }
          },
          "required": [
            "company_mission",
            "supports_sso",
            "is_open_source",
            "is_in_yc"
          ]
        }
      } ]
    }'

Saída:

JSON

{
    "success": true,
    "data": {
      "json": {
        "company_mission": "Rastreamento e extração de dados na web com IA",
        "supports_sso": true,
        "is_open_source": true,
        "is_in_yc": true
      },
      "metadata": {
        "title": "Firecrawl",
        "description": "Rastreamento e extração de dados na web com IA",
        "robots": "follow, index",
        "ogTitle": "Firecrawl",
        "ogDescription": "Rastreamento e extração de dados na web com IA",
        "ogUrl": "https://firecrawl.dev/",
        "ogImage": "https://firecrawl.dev/og.png",
        "ogLocaleAlternate": [],
        "ogSiteName": "Firecrawl"
        "sourceURL": "https://firecrawl.dev/"
      },
    }
}

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.

from firecrawl import Firecrawl

app = Firecrawl(
  # Nenhuma API key necessária para começar — adicione uma para limites de taxa mais altos:
  # api_key="fc-YOUR-API-KEY",
)

result = app.scrape(
    'https://firecrawl.dev',
    formats=[{
      "type": "json",
      "prompt": "Extract the company mission from the page."
    }],
    only_main_content=False,
    timeout=120000
)

print(result)

import { Firecrawl } from "firecrawl";

const app = new Firecrawl({
  // Nenhuma API key necessária para começar — adicione uma para limites de taxa mais altos:
  // apiKey: "fc-YOUR_API_KEY",
});

const result = await app.scrape("https://firecrawl.dev", {
  formats: [{
    type: "json",
    prompt: "Extract the company mission from the page."
  }]
});

console.log(result);

# Nenhuma API key necessária para começar — adicione -H "Authorization: Bearer YOUR_API_KEY" para limites de taxa mais altos:
curl -X POST https://api.firecrawl.dev/v2/scrape \
    -H 'Content-Type: application/json' \
    -d '{
      "url": "https://firecrawl.dev",
      "formats": [{
        "type": "json",
        "prompt": "Extract the company mission from the page."
      }]
    }'

Resultado:

JSON

{
    "success": true,
    "data": {
      "json": {
        "company_mission": "Raspagem e extração de dados na web com IA",
      },
      "metadata": {
        "title": "Firecrawl",
        "description": "Raspagem e extração de dados na web com IA",
        "robots": "seguir, indexar",
        "ogTitle": "Firecrawl",
        "ogDescription": "Raspagem e extração de dados na web com IA",
        "ogUrl": "https://firecrawl.dev/",
        "ogImage": "https://firecrawl.dev/og.png",
        "ogLocaleAlternate": [],
        "ogSiteName": "Firecrawl",
        "sourceURL": "https://firecrawl.dev/"
      },
    }
}

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:

from firecrawl import Firecrawl
from pydantic import BaseModel

app = Firecrawl(
  # Nenhuma API key necessária para começar — adicione uma para limites de taxa mais altos:
  # api_key="fc-YOUR-API-KEY",
)

class CompanyInfo(BaseModel):
    company_mission: str
    supports_sso: bool
    is_open_source: bool
    is_in_yc: bool

result = app.scrape(
    'https://firecrawl.dev/',
    formats=[{
        "type": "json",
        "schema": CompanyInfo.model_json_schema()
    }]
)

print(result)

import { Firecrawl } from "firecrawl";
import { z } from "zod";

const app = new Firecrawl({
  // Nenhuma API key necessária para começar — adicione uma para limites de taxa mais altos:
  // apiKey: "fc-YOUR_API_KEY",
});

const companyInfoSchema = z.object({
  company_mission: z.string(),
  supports_sso: z.boolean(),
  is_open_source: z.boolean(),
  is_in_yc: z.boolean()
});

const result = await app.scrape("https://firecrawl.dev/", {
  formats: [{
    type: "json",
    schema: companyInfoSchema
  }]
});

console.log(result);

# Nenhuma API key é necessária para começar — adicione -H "Authorization: Bearer YOUR_API_KEY" para limites de taxa mais altos:
curl -X POST https://api.firecrawl.dev/v2/scrape \
    -H 'Content-Type: application/json' \
    -d '{
      "url": "https://firecrawl.dev/",
      "formats": [{
        "type": "json",
        "schema": {
          "type": "object",
          "properties": {
            "company_mission": {
              "type": "string"
            },
            "supports_sso": {
              "type": "boolean"
            },
            "is_open_source": {
              "type": "boolean"
            },
            "is_in_yc": {
              "type": "boolean"
            }
          },
          "required": [
            "company_mission",
            "supports_sso",
            "is_open_source",
            "is_in_yc"
          ]
        }
      }]
    }'

Resultado:

Output

{
  "success": true,
  "data": {
    "json": {
      "company_mission": "Transformar sites em dados prontos para LLM",
      "supports_sso": true,
      "is_open_source": true,
      "is_in_yc": true
    }
  }
}

Opções do formato JSON

Ao usar o modo JSON na v2, inclua um object em formats com o schema 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 schema).
prompt: prompt opcional para orientar a extração (também usado para extração sem schema).
checkPromptInjection: descontinuado. Use a opção de scraping checkPromptInjection no nível superior (consulte Detecção de injeção de prompt). Um valor definido aqui continua sendo respeitado.

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

Detecção de injeção de prompt

Páginas web podem conter texto oculto criado para sequestrar um LLM — por exemplo, instruções que dizem ao modelo para ignorar seu schema e retornar dados controlados por um invasor. Se você fizer scraping de URLs não confiáveis ou enviadas por usuários, defina a opção de scraping de nível superior checkPromptInjection para verificar o conteúdo da página antes que qualquer formato baseado em LLM (como json, summary ou question) seja executado. Ela funciona com qualquer formato, exceto rawBase64, inclusive em um scraping simples em markdown:

{
  "url": "https://example.com",
  "formats": [
    {
      "type": "json",
      "schema": { "type": "object", "properties": { "title": { "type": "string" } } }
    }
  ],
  "checkPromptInjection": true
}

Como funciona:

Uma chamada dedicada ao classificador inspeciona o conteúdo da página uma vez por scraping, antes da execução de qualquer formato baseado em LLM, o que acrescenta a latência do classificador à request.
Se uma tentativa de injeção de prompt for detectada, a request falhará com um HTTP 403 e o código de erro SCRAPE_PROMPT_INJECTION_DETECTED. Nenhum resultado será retornado.
Se a verificação não conseguir analisar todo o conteúdo (por exemplo, porque a chamada ao classificador falhou ou o conteúdo da página tem mais de 2.000.000 caracteres), o scraping continua, a resposta inclui um warning e a verificação não é cobrada.
A verificação é cobrada como +4 créditos quando é executada. Se o scraping falhar após a execução da verificação (inclusive quando uma injeção é detectada e a request é 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.

A opção também funciona na extração em lote e em scrapeOptions para rastreamento, busca e monitores. Definir checkPromptInjection no object de formato json ainda funciona, mas está descontinuado. Na v1, a opção é jsonOptions.checkPromptInjection. Os SDKs a expõem como checkPromptInjection (JS) e check_prompt_injection (Python).

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:

{
  "type": "object",
  "properties": {
    "product_name": {
      "type": ["string", "null"],
      "description": "Full descriptive product name as shown on the page. Return null if not found."
    },
    "installation_type": {
      "type": ["string", "null"],
      "description": "Installation type from the Specifications section. Return null if not found.",
      "enum": ["Deck-mount", "Wall-mount", "Countertop", "Drop-in", "Undermount"]
    },
    "flow_rate_gpm": {
      "type": ["string", "null"],
      "description": "Flow rate in GPM from the Specifications section. Return null if not found."
    }
  }
}

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:

{
  "type": "object",
  "properties": {
    "people": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "role": { "type": "string" },
          "department": { "type": "string" }
        }
      }
    }
  }
}

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.

Primeiros passos

Endpoints principais

Mais

Guias de início rápido

Guias para desenvolvedores

Webhooks

Casos de uso

Outros

Como contribuir

Modo JSON - Resultado Estruturado

Raspe e extraia dados estruturados com o Firecrawl

Extraia dados estruturados

Modo JSON via /scrape

Dados estruturados sem esquema

Exemplo real: extraindo informações de empresas

Opções do formato JSON

Detecção de injeção de prompt

Dicas para extração consistente

​Raspe e extraia dados estruturados com o Firecrawl

​Extraia dados estruturados

​Modo JSON via /scrape

​Dados estruturados sem esquema

​Exemplo real: extraindo informações de empresas

​Opções do formato JSON

​Detecção de injeção de prompt

​Dicas para extração consistente

Raspe e extraia dados estruturados com o Firecrawl

Extraia dados estruturados

Modo JSON via /scrape

Dados estruturados sem esquema

Exemplo real: extraindo informações de empresas

Opções do formato JSON

Detecção de injeção de prompt

Dicas para extração consistente