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 的提取) 。

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

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 格式选项

保持提取一致性的技巧

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

​提取结构化数据

​通过 /scrape 的 JSON 模式

​无需 schema 的结构化数据

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

​JSON 格式选项

​保持提取一致性的技巧

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

提取结构化数据

通过 /scrape 的 JSON 模式

无需 schema 的结构化数据

真实案例：提取公司信息

JSON 格式选项

保持提取一致性的技巧