> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firecrawl.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Modo JSON - Resultado Estruturado
> Extraia dados estruturados de páginas com LLMs
**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).
**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](/pt-BR/api-reference/errors) — 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](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.
### Modo JSON via /scrape
Usado para extrair dados estruturados de páginas extraídas.
```python Python theme={null}
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)
```
```js Node theme={null}
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);
```
```bash cURL theme={null}
# 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 JSON theme={null}
{
"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.
```python Python theme={null}
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)
```
```js Node theme={null}
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);
```
```bash cURL theme={null}
# 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 JSON theme={null}
{
"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/"
},
}
}
```
Aqui está um exemplo completo de extração de informações estruturadas de empresas a partir de um site:
```python Python theme={null}
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)
```
```js Node theme={null}
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);
```
```bash cURL theme={null}
# 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:
```json Output theme={null}
{
"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 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`.
**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.
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 theme={null}
{
"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 theme={null}
{
"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.