# Modo JSON - Resultado Estruturado (/pt-BR/features/llm-extract)

<!-- agent-signals: reading_time_min: 9 · est_tokens: 4314 · updated: 2026-07-30 -->
Related: [Busca](/pt-BR/features/search.md), [Destaques da Busca](/pt-BR/features/search-highlights.md), [Índice de research](/pt-BR/features/research.md), [Scraping](/pt-BR/features/scrape.md), [Raspagem mais rápida](/pt-BR/features/fast-scraping.md), [Raspagem em lote](/pt-BR/features/batch-scrape.md)

**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](/pt-BR/features/agent).
* Comparação completa: [Como escolher o Extrator de Dados](/pt-BR/developer-guides/usage-guides/choosing-the-data-extractor).

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

<Note>
  Para falhas na validação de esquema e outros erros de extração, consulte 

  [Erros](/pt-BR/api-reference/errors)

   — problemas específicos de extração normalmente aparecem como respostas 

  `400`

   ou 

  `422`

  .
</Note>

<div id="scrape-and-extract-structured-data-with-firecrawl">
  ## Raspe e extraia dados estruturados com o Firecrawl [#raspe-e-extraia-dados-estruturados-com-o-firecrawl]
</div>

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](https://docs.firecrawl.dev/api-reference/endpoint/scrape)

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.

<div id="extract-structured-data">
  ## Extraia dados estruturados [#extraia-dados-estruturados]
</div>

<div id="json-mode-via-scrape">
  ### Modo JSON via /scrape [#modo-json-via-scrape]
</div>

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

<CodeGroup>
  <CodeBlockTabs defaultValue="Python" groupId="curl+node+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Node">
        Node
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="cURL">
        cURL
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="Python">
      ```python  
      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)
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Node">
      ```js  
      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);
      ```
    </CodeBlockTab>

    <CodeBlockTab value="cURL">
      ```bash  
      # 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"
                ]
              }
            } ]
          }'
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

Saída:

```json title="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/"
      },
    }
}
```

<div id="structured-data-without-schema">
  ### Dados estruturados sem esquema [#dados-estruturados-sem-esquema]
</div>

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

<CodeGroup>
  <CodeBlockTabs defaultValue="Python" groupId="curl+node+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Node">
        Node
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="cURL">
        cURL
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="Python">
      ```python  
      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)
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Node">
      ```js  
      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);
      ```
    </CodeBlockTab>

    <CodeBlockTab value="cURL">
      ```bash  
      # 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."
            }]
          }'
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

Resultado:

```json title="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/"
      },
    }
}
```

<div id="real-world-example-extracting-company-information">
  ### Exemplo real: extraindo informações de empresas [#exemplo-real-extraindo-informações-de-empresas]
</div>

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

<CodeGroup>
  <CodeBlockTabs defaultValue="Python" groupId="curl+node+python">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="Python">
        Python
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Node">
        Node
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="cURL">
        cURL
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="Python">
      ```python  
      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)
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Node">
      ```js  
      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);
      ```
    </CodeBlockTab>

    <CodeBlockTab value="cURL">
      ```bash  
      # 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"
                ]
              }
            }]
          }'
      ```
    </CodeBlockTab>
  </CodeBlockTabs>
</CodeGroup>

Resultado:

```json title="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
    }
  }
}
```

<div id="json-format-options">
  ### Opções do formato JSON [#opções-do-formato-json]
</div>

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`: JSON Schema 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).

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

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

<div id="tips-for-consistent-extraction">
  ## Dicas para extração consistente [#dicas-para-extração-consistente]
</div>

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:**

```json
{
  "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:

```json
{
  "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](https://www.firecrawl.dev/agent-onboarding/SKILL.md) para ver instruções de onboarding automatizado.