JSON 模式 | Firecrawl

选择合适的工具。 当你只有一个 URL，并且想从该页面提取字段时，JSON 模式 (本页) 就是合适的选择。

对于任何超出单个 URL 的场景——例如多个 URL、URL 模式或代理发现——请参见代理。
完整对比：如何选择数据提取器。

v2 API 变更： v2 已完全支持 JSON schema 提取，但 API 格式有所调整。在 v2 中，schema 直接嵌入到 format 对象中，写法为 formats: [{type: "json", schema: {...}}]。v1 的 jsonOptions 参数在 v2 中已被移除。

对于 schema 验证失败及其他提取错误，请参见 Errors——提取相关问题通常会表现为 400 或 422 响应。

使用 Firecrawl 抓取并提取结构化数据

Firecrawl 借助 AI 通过 3 个步骤从网页获取结构化数据：

设置 Schema (可选) ： 定义一个 JSON Schema (采用 OpenAI 的格式) 来明确所需数据；如果不需要严格的 Schema，也可仅提供一个 prompt，并附上网页 URL。
发起请求： 使用 JSON 模式将你的 URL 和 Schema 发送到我们的 /scrape 端点。查看方法： Scrape Endpoint Documentation
获取数据： 返回与你的 Schema 匹配的干净、结构化数据，可直接使用。

这使你能快速、轻松地按所需 formats 获取网页数据。

提取结构化数据

通过 /scrape 的 JSON 模式

用于从抓取的页面中提取结构化数据。

from firecrawl import Firecrawl
from pydantic import BaseModel

app = Firecrawl(
  # 无需 API 密钥即可开始使用 — 添加一个以获得更高的限流额度：
  # 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()
    }],
    only_main_content=False,
    timeout=120000
)

print(result)

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

const app = new Firecrawl({
  // 无需 API 密钥即可开始使用——添加一个以获得更高的限流额度：
  // 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);

# 无需 API 密钥即可开始使用 — 添加 -H "Authorization: Bearer YOUR_API_KEY" 以获得更高的限流额度：
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"
          ]
        }
      } ]
    }'

输出：

JSON

{
    "success": true,
    "data": {
      "json": {
        "company_mission": "AI 赋能的网页抓取与数据抽取",
        "supports_sso": true,
        "is_open_source": true,
        "is_in_yc": true
      },
      "metadata": {
        "title": "Firecrawl",
        "description": "AI 赋能的网页抓取与数据抽取",
        "robots": "follow, index",
        "ogTitle": "Firecrawl",
        "ogDescription": "AI 赋能的网页抓取与数据抽取",
        "ogUrl": "https://firecrawl.dev/",
        "ogImage": "https://firecrawl.dev/og.png",
        "ogLocaleAlternate": [],
        "ogSiteName": "Firecrawl",
        "sourceURL": "https://firecrawl.dev/"
      },
    }
}

无需 schema 的结构化数据

你也可以只向端点传入一个 prompt，在没有 schema 的情况下进行提取。LLM 会自行确定数据结构。

from firecrawl import Firecrawl

app = Firecrawl(
  # 无需 API 密钥即可开始使用 — 添加一个以获得更高的限流额度：
  # 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({
  // 无需 API 密钥即可开始使用 — 添加一个以获得更高的限流上限：
  // 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);

# 无需 API 密钥即可开始使用——添加 -H "Authorization: Bearer YOUR_API_KEY" 可获得更高限流：
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."
      }]
    }'

输出：

JSON

{
    "success": true,
    "data": {
      "json": {
        "company_mission": "AI 驱动的网页抓取与数据抽取",
      },
      "metadata": {
        "title": "Firecrawl",
        "description": "AI 驱动的网页抓取与数据抽取",
        "robots": "follow, index",
        "ogTitle": "Firecrawl",
        "ogDescription": "AI 驱动的网页抓取与数据抽取",
        "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 密钥即可开始使用 — 添加一个以获得更高的限流额度：
  # 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({
  // 无需 API 密钥即可开始使用 — 添加一个以获得更高的限流额度：
  // 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);

# 无需 API 密钥即可开始使用——添加 -H "Authorization: Bearer YOUR_API_KEY" 可获得更高限流额度：
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"
          ]
        }
      }]
    }'

输出：

Output

{
  "success": true,
  "data": {
    "json": {
      "company_mission": "将网站转换为 LLM 可用数据",
      "supports_sso": true,
      "is_open_source": true,
      "is_in_yc": true
    }
  }
}

JSON 格式选项

在 v2 中使用 JSON 模式时，需要在 formats 中直接包含一个内嵌 schema 的对象： formats: [{ type: 'json', schema: { ... }, prompt: '...' }] 参数：

schema: 描述所需结构化输出的 JSON Schema (基于 schema 的提取为必填) 。
prompt: 可选提示，用于引导提取 (也用于无 schema 的提取) 。
checkPromptInjection: 可选布尔值 (默认值为 false) 。启用后，Firecrawl 会在运行提取前扫描已抓取页面内容中的 prompt 注入尝试。请参见 Prompt 注入检测。

重要说明： 与 v1 不同，v2 中没有单独的 jsonOptions 参数。schema 必须直接包含在 formats 数组中的 format 对象内。

prompt 注入检测

网页可能包含精心构造的隐藏文本，用于劫持基于 LLM 的提取——例如，指示模型忽略你的 schema 并返回由攻击者控制的数据。如果你从不受信任或用户提交的 URL 中提取数据，可以选择启用防护机制，在提取运行前检查抓取到的内容：

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

工作原理：

专用分类器会检查抓取的页面内容 (与提取并行运行，因此启用后不会拖慢正常抓取) 。
如果检测到 prompt 注入尝试，请求会失败并返回 HTTP 403 和错误代码 SCRAPE_PROMPT_INJECTION_DETECTED——不会返回任何提取结果。
该检查运行时，会在标准 JSON 格式成本的基础上额外计费 +4 额度。如果检查运行后抓取失败 (包括检测到注入且请求被封禁时) ，则会计费 5 额度，而不是失败抓取通常的 0 额度，因为分类器调用仍已运行。

在 v1 中，同一选项以 jsonOptions.checkPromptInjection 的形式提供。所有官方 SDK 中也提供了该选项 (例如 JS SDK 中的 checkPromptInjection、Python SDK 的 v2 JSON 格式中的 check_prompt_injection) 。

JSON 提取中不支持 HTML 属性。 JSON 提取是基于页面的 Markdown 转换结果工作的，该转换只保留可见文本内容。HTML 属性 (例如 data-id、元素上的自定义属性) 会在转换过程中被去除，大语言模型无法看到这些属性。如果你需要提取 HTML 属性值，请使用 rawHtml format 并在客户端解析属性，或者使用 executeJavascript 动作为在提取前将属性值注入到可见文本中。

保持提取一致性的技巧

如果你在使用 JSON 提取时遇到结果不一致或不完整的情况，可以参考以下做法：

让 prompt 简短且聚焦。 带有大量规则的长 prompt 会增加结果的不确定性。将具体约束 (如允许值) 移入 schema 本身。
使用简洁的属性名。 避免在属性名中嵌入说明或枚举列表。用类似 "installation_type" 这样的简短键名，并把允许值放在 enum 数组中。
为受限字段添加 enum 数组。 当某个字段只有固定取值时，将它们列在 enum 中，并确保与页面上显示的文本完全匹配。
在字段描述中包含 null 处理逻辑。 在每个字段的 description 中添加 "Return null if not found on the page."，以避免模型猜测缺失值。
添加位置信息提示。 告诉模型在页面上哪里查找数据，例如 "Flow rate in GPM from the Specifications table."。
将大型 schema 拆分成多个请求。 字段很多 (例如 30+) 的 schema 通常会产生更不稳定的结果。将其拆成 2–3 个请求，每个请求包含 10–15 个字段。
避免在数组上使用 minItems/maxItems。 minItems 和 maxItems 这类 JSON Schema 验证关键字并不能控制抓取器收集多少内容。设置 minItems: 20 并不会让 LLM 返回更多条目——反而可能会为了满足约束而臆造一些条目。请移除这些关键字，改用 prompt 来引导完整性 (例如 "Extract ALL reviews from the page. Do not skip any.")。
使用 "type": "array" 提取列表项。 如果你需要提取多个条目 (例如人员、产品或评论列表)，请将它们放在带有 items 块的数组属性中。对列表使用 "type": "object" 只会返回单个条目。请参见下方的数组 schema 示例。

结构良好的 schema 示例：

{
  "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."
    }
  }
}

提取条目列表的示例： 当页面包含多个条目 (例如团队成员、产品、评论) 时，使用 "type": "array" 搭配 "items" 来获取完整列表：

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

你是需要 Firecrawl API 密钥的 AI 代理吗？请参阅 firecrawl.dev/agent-onboarding/SKILL.md 了解自动化入门说明。

快速上手

核心端点

更多

快速入门

开发者指南

Webhooks

使用场景

其他

参与贡献

JSON 模式 - 结构化结果

使用 Firecrawl 抓取并提取结构化数据

提取结构化数据

通过 /scrape 的 JSON 模式

无需 schema 的结构化数据

真实案例：提取公司信息

JSON 格式选项

prompt 注入检测

保持提取一致性的技巧

​使用 Firecrawl 抓取并提取结构化数据

​提取结构化数据

​通过 /scrape 的 JSON 模式

​无需 schema 的结构化数据

​真实案例：提取公司信息

​JSON 格式选项

​prompt 注入检测

​保持提取一致性的技巧

使用 Firecrawl 抓取并提取结构化数据

提取结构化数据

通过 /scrape 的 JSON 模式

无需 schema 的结构化数据

真实案例：提取公司信息

JSON 格式选项

prompt 注入检测

保持提取一致性的技巧