Mudança na API v2: A extração de schema JSON é totalmente suportada na v2, mas o formato da API mudou. Na v2, o schema é incorporado diretamente no objeto de formatos como formats: [{type: "json", schema: {...}}]. O parâmetro jsonOptions da v1 não existe mais na v2.
-
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.
Usado para extrair dados estruturados de páginas extraídas.
from firecrawl import Firecrawl
from pydantic import BaseModel
app = Firecrawl(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)
{
"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
prompt para o endpoint. O LLM escolhe a estrutura dos dados.
from firecrawl import Firecrawl
app = Firecrawl(api_key="fc-YOUR-API-KEY")
result = app.scrape(
'https://firecrawl.dev',
formats=[{
"type": "json",
"prompt": "Extraia a missão da empresa presente na página."
}],
only_main_content=False,
timeout=120000
)
print(result)
{
"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/"
},
}
}
from firecrawl import Firecrawl
from pydantic import BaseModel
app = Firecrawl(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)
{
"success": true,
"data": {
"json": {
"company_mission": "Transformar sites em dados prontos para LLM",
"supports_sso": true,
"is_open_source": true,
"is_in_yc": true
}
}
}
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.
- 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 schema.
- 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 schemas grandes em solicitações menores. Schemas com muitos campos (por exemplo, 30+) produzem resultados menos consistentes. Divida-os em 2–3 solicitações de 10–15 campos cada.
Exemplo de um schema 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."
}
}
}
