Skip to main content
Firecrawl Docs

JSONモード - 構造化結果

LLMでページから構造化データを抽出する
2 min read

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

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

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

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

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

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

  1. スキーマを設定 (任意) : 取得したいデータを指定するために (OpenAIの形式の) JSONスキーマを定義するか、厳密なスキーマが不要な場合はウェブページのURLとpromptだけを指定します。

  2. リクエストを送信: URLとスキーマを、JSONモードを用いて/scrape エンドポイントに送ります。詳しくはこちら: Scrape Endpoint Documentation

  3. データを取得: スキーマに一致するクリーンな構造化データが返ってきます。すぐに利用できます。

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

構造化データの抽出#

/scrape による JSONモード#

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

出力:

JSON

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

エンドポイントに prompt を渡すだけで、スキーマなしで抽出できます。データの構造は LLM が決定します。

出力:

JSON

実例：企業情報の抽出#

以下は、ウェブサイトから構造化された企業情報を抽出する包括的な例です：

出力：

Output

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

v2 で JSONモード を使用する場合、formats にスキーマを直接埋め込んだオブジェクトを含めます:

formats: [{ type: 'json', schema: { ... }, prompt: '...' }]

パラメータ:

  • schema: 取得したい構造化出力を記述する JSON Schema (スキーマベースの抽出では必須) 。
  • prompt: 抽出をガイドするための任意のプロンプト (スキーマなしの抽出でも使用) 。
  • checkPromptInjection: 任意のブール値 (デフォルトは false) 。有効にすると、Firecrawl は抽出を実行する前に、スクレイピングしたページコンテンツにプロンプトインジェクションの試みがないかスキャンします。プロンプトインジェクションの検出を参照してください。

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

プロンプトインジェクションの検出#

Web ページには、LLM ベースの抽出を乗っ取るよう作成された隠しテキストが含まれている場合があります。たとえば、スキーマを無視して攻撃者が制御するデータを返すようモデルに指示するテキストです。信頼できない URL やユーザー送信の URL から抽出する場合は、抽出の実行前にスクレイピングしたコンテンツをチェックするオプトインの保護機能を有効にできます:

仕組み:

  • 専用の分類器呼び出しがスクレイピングされたページコンテンツを検査します (抽出と並行して実行されるため、有効にしても問題のないスクレイピングが遅くなることはありません) 。
  • プロンプトインジェクションの試みが検出されると、リクエストは HTTP 403 とエラーコード SCRAPE_PROMPT_INJECTION_DETECTED で失敗し、抽出結果は返されません。
  • チェックが実行される場合、標準の JSON フォーマットのコストに加えて +4 クレジットが課金されます。チェックの実行後にスクレイピングが失敗した場合 (インジェクションが検出されてリクエストがブロックされた場合を含む) 、分類器呼び出しはすでに実行されているため、失敗したスクレイピングに通常課金される 0 クレジットではなく、5 クレジットが課金されます。

v1 では、同じオプションを jsonOptions.checkPromptInjection として利用できます。また、すべての公式 SDK でも利用できます (例: JS SDK の checkPromptInjection、Python SDK の v2 JSON フォーマットの check_prompt_injection) 。

Note

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 項目だけです。以下の配列スキーマの例を参照してください。

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

項目のリストを抽出する例:

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

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

バッチスクレイピング変更追跡