JSONモード | Firecrawl

適切なツールの選び方。 JSONモード (このページ) は、1つのURL があり、その1ページからフィールドを抽出したい場合に適しています。

1 つの URL だけではない場合 — 複数の URL、URL パターン、またはエージェントによる探索 — については、Agentを参照してください。
詳細な比較: データ抽出機能の選び方。

v2 APIの変更: JSONスキーマ抽出はv2で完全にサポートされていますが、APIのフォーマットが変更されました。v2では、スキーマは formats: [{type: "json", schema: {...}}] のようにフォーマットオブジェクト内に直接埋め込まれます。v1の jsonOptions パラメータはv2では廃止されています。

スキーマ検証の失敗やその他の抽出エラーについては、Errors を参照してください。抽出固有の問題は通常、400 または 422 のレスポンスとして返されます。

Firecrawlで構造化データをスクレイプして抽出する

FirecrawlはAIを用いて、ウェブページから構造化データを3ステップで取得します:

スキーマを設定 (任意) : 取得したいデータを指定するために (OpenAIの形式の) JSONスキーマを定義するか、厳密なスキーマが不要な場合はウェブページのURLとpromptだけを指定します。
リクエストを送信: URLとスキーマを、JSONモードを用いて/scrape エンドポイントに送ります。詳しくはこちら: Scrape Endpoint Documentation
データを取得: スキーマに一致するクリーンな構造化データが返ってきます。すぐに利用できます。

これにより、必要なフォーマットでウェブデータを素早く簡単に取得できます。

構造化データの抽出

/scrape による JSONモード

スクレイピングしたページから構造化データを抽出するために使用します。

from firecrawl import Firecrawl
from pydantic import BaseModel

app = Firecrawl(
  # 始めるのにAPIキーは不要です — より高いRate Limitsを得るには追加してください:
  # 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/"
      },
    }
}

スキーマ不要の構造化データ

エンドポイントに prompt を渡すだけで、スキーマなしで抽出できます。データの構造は 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キーは不要です — より高いrate limitsが必要な場合は追加してください:
  // 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 keyは不要です — より高いrate limitsを利用するには -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": "WebサイトをLLM対応データに変換",
      "supports_sso": true,
      "is_open_source": true,
      "is_in_yc": true
    }
  }
}

JSON フォーマットのオプション

v2 で JSONモードを使用する場合、formats にスキーマを直接埋め込んだオブジェクトを含めます: formats: [{ type: 'json', schema: { ... }, prompt: '...' }] パラメータ:

schema: 取得したい構造化出力を記述する JSON Schema (スキーマベースの抽出では必須) 。
prompt: 抽出をガイドするための任意のプロンプト (スキーマなしの抽出でも使用) 。

重要: v1 と異なり、v2 には個別の jsonOptions パラメータはありません。スキーマは formats 配列内のフォーマットオブジェクトに直接含める必要があります。

HTML 属性は JSON 抽出では利用できません。 JSON 抽出はページを markdown に変換した結果に対して実行され、この変換では表示テキストのみが保持されます。HTML 属性 (例: data-id、要素上のカスタム属性) は変換時に削除されるため、LLM からは参照できません。HTML 属性値を抽出する必要がある場合は、rawHtml フォーマットを使用してクライアント側で属性をパースするか、executeJavascript アクションを使って抽出前に属性値を表示テキストへ埋め込んでください。

一貫した抽出のためのヒント

JSON 抽出の結果が一貫しなかったり不完全だったりする場合、次のベストプラクティスが役立ちます。

プロンプトは短く、焦点を絞る。 多くのルールを含む長いプロンプトはばらつきを増やします。具体的な制約 (許可される値など) はプロンプトではなくスキーマ側に移してください。
プロパティ名は簡潔にする。 プロパティ名の中に指示や列挙リストを埋め込まないでください。"installation_type" のような短いキーを使い、許可される値は enum 配列に入れます。
制約されたフィールドには enum 配列を追加する。 フィールドが固定の値セットを持つ場合、それらを enum に列挙し、ページ上に表示されているテキストと完全に一致させてください。
フィールドの説明に null ハンドリングを含める。 モデルが欠損値を推測しないよう、各フィールドの description に "Return null if not found on the page." を追加してください。
場所のヒントを追加する。 モデルにページ上のどこからデータを取得するかを伝えます (例: "Flow rate in GPM from the Specifications table.") 。
大きなスキーマは小さなリクエストに分割する。 フィールド数が多いスキーマ (例: 30 項目以上) は結果の一貫性が下がります。10〜15 フィールドずつ、2〜3 個のリクエストに分割してください。
配列に 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" を使うと、返されるのは 1 項目だけです。以下の配列スキーマの例を参照してください。

よく構造化されたスキーマの例:

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

項目のリストを抽出する例: ページに複数の項目 (例: チームメンバー、製品、レビュー) が含まれている場合、一覧全体を取得するには "items" とともに "type": "array" を使用します。

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

AI エージェントで、Firecrawl API キーが必要ですか？自動オンボーディングの手順については、firecrawl.dev/agent-onboarding/SKILL.md を参照してください。

​Firecrawlで構造化データをスクレイプして抽出する

​構造化データの抽出

​/scrape による JSONモード

​スキーマ不要の構造化データ

​実例：企業情報の抽出

​JSON フォーマットのオプション

​一貫した抽出のためのヒント

Firecrawlで構造化データをスクレイプして抽出する

構造化データの抽出

/scrape による JSONモード

スキーマ不要の構造化データ

実例：企業情報の抽出

JSON フォーマットのオプション

一貫した抽出のためのヒント