高度なスクレイピングガイド

このガイドでは、Firecrawl の各エンドポイントと、用意されたすべてのパラメータを使いこなす方法を順を追って解説します。

Firecrawl で行う基本的なスクレイピング

単一のページをスクレイピングしてクリーンなMarkdownコンテンツを取得するには、/scrape エンドポイントを使用します。

# pip install firecrawl-py

from firecrawl import Firecrawl

firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")

doc = firecrawl.scrape("https://firecrawl.dev")

print(doc.markdown)

PDFのスクレイピング

FirecrawlはPDFに対応しています。PDFを確実に解析したい場合は、parsers オプション（例: parsers: ["pdf"]）を使用してください。

スクレイピングのオプション

/scrape エンドポイントを使用する際は、以下のオプションでスクレイピングをカスタマイズできます。

フォーマット (`formats`)

型: array
文字列: ["markdown", "links", "html", "rawHtml", "summary", "images"]
オブジェクト形式:
- JSON: { type: "json", prompt, schema }
- スクリーンショット: { type: "screenshot", fullPage?, quality?, viewport? }
- changeTracking（変更追跡）: { type: "changeTracking", modes?, prompt?, schema?, tag? }（markdown が必要）
デフォルト: ["markdown"]

ページ全体のコンテンツとメインコンテンツ（`onlyMainContent`）

タイプ: boolean
説明: 既定ではスクレイパーはメインコンテンツのみを返します。ページ全体のコンテンツを返すには false に設定してください。
デフォルト: true

含めるタグ（`includeTags`）

Type: array
Description: スクレイプに含める HTML のタグ／クラス／ID。

除外タグ（`excludeTags`）

型: array
説明: スクレイプ対象から除外する HTML のタグ・クラス・ID。

ページの準備完了を待つ (`waitFor`)

型: integer
説明: スクレイピング前に追加で待機する時間（ミリ秒単位。必要な場合のみ設定してください）。この待機時間は、Firecrawl のスマート待機機能による待機時間に加えて適用されます。
デフォルト: 0

鮮度とキャッシュ（`maxAge`）

タイプ: integer（ミリ秒）
説明: ページのキャッシュが maxAge 以内に更新されたものであれば、Firecrawl は即座にそれを返し、そうでなければ新規にスクレイプしてキャッシュを更新します。常に最新を取得するには 0 を設定します。
デフォルト: 172800000（2日）

リクエストのタイムアウト (`timeout`)

型: integer
説明: 中止までの最大時間（ミリ秒）。
デフォルト: 30000（30秒）

PDF 解析（`parsers`）

型: array
説明: 解析動作を制御します。PDF を解析するには、parsers: ["pdf"] を設定します。

アクション (`actions`)

/scrape エンドポイントを使用する場合、Firecrawl ではスクレイピングを実行する前に、Webページ上でさまざまなアクションを実行するよう指定できます。これは、動的コンテンツとの対話、ページ遷移、あるいはユーザー操作が必要なコンテンツへのアクセスに特に有用です。

Type: array
Description: スクレイピング前に実行するブラウザステップのシーケンス。
Supported actions:
- wait - ページの読み込みを待機: { type: "wait", milliseconds: number } または { type: "wait", selector: string }
- click - 要素をクリック: { type: "click", selector: string, all?: boolean }
- write - フィールドにテキストを入力: { type: "write", text: string }（事前に click で要素へフォーカスしておく必要あり）
- press - キーボードキーを押下: { type: "press", key: string }
- scroll - ページをスクロール: { type: "scroll", direction: "up" | "down", selector?: string }
- screenshot - スクリーンショットを取得: { type: "screenshot", fullPage?: boolean, quality?: number, viewport?: { width: number, height: number } }
- scrape - サブ要素をスクレイピング: { type: "scrape" }
- executeJavascript - JS コードを実行: { type: "executeJavascript", script: string }
- pdf - PDF を生成: { type: "pdf", format?: string, landscape?: boolean, scale?: number }

from firecrawl import Firecrawl

firecrawl = Firecrawl(api_key='fc-YOUR-API-KEY')

doc = firecrawl.scrape('https://example.com', {
  'actions': [
    { 'type': 'wait', 'milliseconds': 1000 },
    { 'type': 'click', 'selector': '#accept' },
    { 'type': 'scroll', 'direction': 'down' },
    { 'type': 'click', 'selector': '#q' },
    { 'type': 'write', 'text': 'firecrawl' },
    { 'type': 'press', 'key': 'Enter' },
    { 'type': 'wait', 'milliseconds': 2000 }
  ],
  'formats': ['markdown']
})

print(doc.markdown)

アクション実行に関する注意事項

write アクション: write を使う前に、必ず click アクションで要素をフォーカスする必要があります。テキストはキーボード入力をシミュレートするため、1文字ずつ順に入力されます。
scroll セレクター: ページ全体ではなく特定の要素だけをスクロールしたい場合は、scroll に selector パラメータを指定します。
セレクター付き wait: 特定の要素が表示されるまで待ちたい場合は、selector パラメータを指定した wait を使用します。固定時間だけ待機したい場合は、milliseconds を指定します。
アクションは逐次実行: アクションは指定された順番で実行され、Firecrawl は次のアクションに進む前に、ページ上の操作が完了するまで待機します。

高度なアクション例

スクリーンショットを撮影する:

cURL

curl -X POST https://api.firecrawl.dev/v2/scrape \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer fc-YOUR-API-KEY' \
  -d '{
    "url": "https://example.com",
    "actions": [
      { "type": "click", "selector": "#load-more" },
      { "type": "wait", "milliseconds": 1000 },
      { "type": "screenshot", "fullPage": true, "quality": 80 }
    ]
  }'

複数の要素をクリックする:

cURL

curl -X POST https://api.firecrawl.dev/v2/scrape \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer fc-YOUR-API-KEY' \
  -d '{
    "url": "https://example.com",
    "actions": [
      { "type": "click", "selector": ".expand-button", "all": true },
      { "type": "wait", "milliseconds": 500 }
    ],
    "formats": ["markdown"]
  }'

PDF を生成する:

cURL

curl -X POST https://api.firecrawl.dev/v2/scrape \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer fc-YOUR-API-KEY' \
  -d '{
    "url": "https://example.com",
    "actions": [
      { "type": "pdf", "format": "A4", "landscape": false }
    ]
  }'

使い方の例

cURL

curl -X POST https://api.firecrawl.dev/v2/scrape \
    -H '
    Content-Type: application/json' \
    -H 'Authorization: Bearer fc-YOUR-API-KEY' \
    -d '{
      "url": "https://docs.firecrawl.dev",
      "formats": [
        "markdown",
        "links",
        "html",
        "rawHtml",
        { "type": "screenshot", "fullPage": true, "quality": 80 }
      ],
      "includeTags": ["h1", "p", "a", ".main-content"],
      "excludeTags": ["#ad", "#footer"],
      "onlyMainContent": false,
      "waitFor": 1000,
      "timeout": 15000,
      "parsers": ["pdf"]
    }'

この例では、スクレイパーは次を行います:

ページ全体のコンテンツをMarkdownで返します。
レスポンスにMarkdown、raw HTML、HTML、リンク、スクリーンショットを含めます。
HTMLタグの <h1>、<p>、<a> と、クラス .main-content を持つ要素のみを含め、IDが #ad と #footer の要素は除外します。
ページの読み込みのため、スクレイピング前に1000ミリ秒（1秒）待機します。
スクレイプリクエストの最大実行時間を15000ミリ秒（15秒）に設定します。
parsers: ["pdf"] を指定してPDFを明示的に解析します。

APIリファレンスはこちら: Scrape Endpoint Documentation

フォーマットによる JSON 抽出

formats 内で JSON フォーマットオブジェクトを使用して、一度の処理で構造化データを抽出します。

curl -X POST https://api.firecrawl.dev/v2/scrape \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer fc-YOUR-API-KEY' \
  -d '{
    "url": "https://firecrawl.dev",
    "formats": [{
      "type": "json",
      "prompt": "Extract the features of the product",
      "schema": {"type": "object", "properties": {"features": {"type": "object"}}, "required": ["features"]}
    }]
  }'

Extract エンドポイント

ステータスをポーリングしながら非同期に抽出したい場合は、専用の extract ジョブ API を使用します。

import Firecrawl from '@mendable/firecrawl-js';

const firecrawl = new Firecrawl({ apiKey: 'fc-YOUR-API-KEY' });

// 抽出ジョブを開始
const started = await firecrawl.startExtract({
  urls: ['https://docs.firecrawl.dev'],
  prompt: 'Extract title',
  schema: { type: 'object', properties: { title: { type: 'string' } }, required: ['title'] }
});

// ステータスをポーリング
const status = await firecrawl.getExtractStatus(started.id);
console.log(status.status, status.data);

複数ページのクロール

複数のページをクロールするには、/v2/crawl エンドポイントを使用します。

cURL

curl -X POST https://api.firecrawl.dev/v2/crawl \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer fc-あなたのAPIキー' \
    -d '{
      "url": "https://docs.firecrawl.dev"
    }'

IDを返します

{ "id": "1234-5678-9101" }

クロールジョブを確認する

クロールジョブのステータスを確認し、その結果を取得します。

cURL

curl -X GET https://api.firecrawl.dev/v2/crawl/1234-5678-9101 \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer fc-YOUR-API-KEY'

ページネーション/次のURL

コンテンツが10MBを超える場合やクロールジョブがまだ実行中の場合、レスポンスに next パラメータ（結果の次ページへのURL）が含まれる場合があります。

クロール用プロンプトとパラメータのプレビュー

自然言語の prompt を指定すると、Firecrawl がクロール設定を自動で推定します。まずはプレビューしてください：

cURL

curl -X POST https://api.firecrawl.dev/v2/crawl/params-preview \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer fc-YOUR-API-KEY' \
  -d '{
    "url": "https://docs.firecrawl.dev",
    "prompt": "ドキュメントとブログを抽出する"
  }'

クローラーオプション

/v2/crawl エンドポイントでは、次のオプションでクロールの挙動をカスタマイズできます。

includePaths

型: array
説明: インクルード対象とする正規表現パターン。
例: ["^/blog/.*$", "^/docs/.*$"]

excludePaths

型: array
説明: 除外対象を指定する正規表現パターン。
例: ["^/admin/.*$", "^/private/.*$"]

maxDiscoveryDepth

Type: integer
Description: 新規URL発見のための最大探索深度。

limit

Type: integer
Description: クロールするページ数の上限。
Default: 10000

crawlEntireDomain

型: boolean
説明: 兄弟ページや親ページにも探索を拡げ、ドメイン全体をカバーします。
デフォルト: false

allowExternalLinks

Type: boolean
Description: 外部ドメインへのリンクを追跡します。
Default: false

allowSubdomains

型: boolean
説明: メインドメインのサブドメインもクロールします。
既定値: false

delay

Type: number
Description: スクレイピング間の遅延（秒）。
Default: undefined

scrapeOptions

Type: object
Description: スクレイパーのオプション（上記のフォーマット参照）。
Example: { "formats": ["markdown", "links", {"type": "screenshot", "fullPage": true}], "includeTags": ["h1", "p", "a", ".main-content"], "excludeTags": ["#ad", "#footer"], "onlyMainContent": false, "waitFor": 1000, "timeout": 15000}
Defaults: formats: ["markdown"]、既定でキャッシュ有効（maxAge 約2日）

使い方の例

cURL

curl -X POST https://api.firecrawl.dev/v2/crawl \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer fc-YOUR-API-KEY' \
    -d '{
      "url": "https://docs.firecrawl.dev",
      "includePaths": ["^/blog/.*$", "^/docs/.*$"],
      "excludePaths": ["^/admin/.*$", "^/private/.*$"],
      "maxDiscoveryDepth": 2,
      "limit": 1000
    }'

ウェブサイトリンクのマッピング

/v2/map エンドポイントは、指定したウェブサイトに関連する URL を検出します。

使い方

cURL

curl -X POST https://api.firecrawl.dev/v2/map \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer fc-YOUR-API-KEY' \
    -d '{
      "url": "https://docs.firecrawl.dev"
    }'

マッピングオプション

search

Type: string
Description: 指定したテキストを含むリンクをフィルタします。

limit

Type: integer
Description: 返すリンクの最大数
Default: 100

sitemap

Type: "only" | "include" | "skip"
Description: マッピング時のsitemapの利用方法を制御します。
Default: "include"

includeSubdomains

Type: boolean
Description: ウェブサイトのサブドメインを含めるかどうか。
Default: true

該当するAPIリファレンスはこちら: Map Endpoint Documentation お読みいただきありがとうございました。

クイックスタート

新機能

基本機能

ウェブフック

開発者向けガイド

ユースケース

貢献する

​Firecrawl で行う基本的なスクレイピング

​PDFのスクレイピング

​スクレイピングのオプション

​フォーマット (formats)

​ページ全体のコンテンツとメインコンテンツ（onlyMainContent）

​含めるタグ（includeTags）

​除外タグ（excludeTags）

​ページの準備完了を待つ (waitFor)

​鮮度とキャッシュ（maxAge）

​リクエストのタイムアウト (timeout)

​PDF 解析（parsers）

​アクション (actions)

​アクション実行に関する注意事項

​高度なアクション例

​使い方の例

​フォーマットによる JSON 抽出

​Extract エンドポイント

​複数ページのクロール

​クロールジョブを確認する

​ページネーション/次のURL

​クロール用プロンプトとパラメータのプレビュー

​クローラーオプション

​includePaths

​excludePaths

​maxDiscoveryDepth

​limit

​crawlEntireDomain

​allowExternalLinks

​allowSubdomains

​delay

​scrapeOptions

​使い方の例

​ウェブサイトリンクのマッピング

​使い方

​マッピングオプション

​search

​limit

​sitemap

​includeSubdomains

Firecrawl で行う基本的なスクレイピング

PDFのスクレイピング

スクレイピングのオプション

フォーマット (`formats`)

ページ全体のコンテンツとメインコンテンツ（`onlyMainContent`）

含めるタグ（`includeTags`）

除外タグ（`excludeTags`）

ページの準備完了を待つ (`waitFor`)

鮮度とキャッシュ（`maxAge`）

リクエストのタイムアウト (`timeout`)

PDF 解析（`parsers`）

アクション (`actions`)

アクション実行に関する注意事項

高度なアクション例

使い方の例

フォーマットによる JSON 抽出

Extract エンドポイント

複数ページのクロール

クロールジョブを確認する

ページネーション/次のURL

クロール用プロンプトとパラメータのプレビュー

クローラーオプション

includePaths

excludePaths

maxDiscoveryDepth

limit

crawlEntireDomain

allowExternalLinks

allowSubdomains

delay

scrapeOptions

使い方の例

ウェブサイトリンクのマッピング

使い方

マッピングオプション

search

limit

sitemap

includeSubdomains