firecrawl-scraper

Firecrawl Web Scraper スキル

ステータス: 本番環境対応済み ✅ 最終更新日: 2025-10-24 公式ドキュメント: https://docs.firecrawl.dev API バージョン: v2

---

Firecrawl とは？

Firecrawl は、ウェブサイト全体を LLM 対応の Markdown または構造化データに変換するAI 向け Web データ APIです。次の機能を備えています。

• JavaScript のレンダリング - クライアント側の JavaScript を実行して動的コンテンツを取得します
• ボット対策の回避 - CAPTCHA やボット検出システムを突破します
• 形式の変換 - Markdown、JSON、または構造化データとして出力します
• スクリーンショットの取得 - ページの視覚的な表示を保存します
• ブラウザーの自動化 - ヘッドレスブラウザーの全機能を利用できます

---

API エンドポイント

1. /v2/scrape - 単一ページのスクレイピング

単一のウェブページをスクレイピングし、クリーンで構造化されたコンテンツを返します。

ユースケース:

• 記事のコンテンツを抽出する
• 製品の詳細を取得する
• 特定のページをスクレイピングする
• HTML を Markdown に変換する

主なオプション:

• formats: ["markdown", "html", "screenshot"]
• onlyMainContent: true/false（ナビゲーション、フッター、広告を削除します）
• waitFor: スクレイピング開始前に待機する時間（ミリ秒）
• actions: ブラウザー自動化アクション（クリック、スクロールなど）

2. /v2/crawl - サイト全体のクロール

開始 URL からアクセス可能なすべてのページをクロールします。

ユースケース:

• ドキュメントサイト全体をインデックス化する
• ウェブサイトのコンテンツをアーカイブする
• ナレッジベースを構築する
• 複数ページのコンテンツをスクレイピングする

主なオプション:

• limit: クロールするページの最大数
• maxDepth: たどるリンクの深さ
• allowedDomains: 特定のドメインに制限する
• excludePaths: 特定の URL パターンを除外する

3. /v2/map - URL の検出

コンテンツをスクレイピングせずに、ウェブサイト上のすべての URL をマッピングします。

ユースケース:

• サイトマップを見つける
• すべてのページを検出する
• クロール戦略を計画する
• ウェブサイトの構造を監査する

4. /v2/extract - 構造化データの抽出

AI を使用して、ページから指定したデータフィールドを抽出します。

ユースケース:

• 製品の価格と名称を抽出する
• 連絡先情報を解析する
• 構造化データセットを構築する
• カスタムデータスキーマを使用する

主なオプション:

• schema: 必要な構造を定義する Zod または JSON スキーマ
• systemPrompt: AI による抽出方法を指示するプロンプト

---

認証

Firecrawl へのすべてのリクエストには API キーが必要です。

API キーの取得

1. https://www.firecrawl.dev でサインアップします
2. ダッシュボードで「API Keys」に移動します
3. API キーをコピーします（fc- で始まります）

安全な保管

API キーをコードにハードコードしないでください！

# .env file
FIRECRAWL_API_KEY=fc-your-api-key-here

# .env.local (for local development)
FIRECRAWL_API_KEY=fc-your-api-key-here

---

Python SDK の使用方法

インストール

pip install firecrawl-py

最新バージョン: firecrawl-py v4.5.0+

基本的なスクレイピング

import os
from firecrawl import FirecrawlApp

# Initialize client
app = FirecrawlApp(api_key=os.environ.get("FIRECRAWL_API_KEY"))

# Scrape a single page
result = app.scrape_url(
    url="https://example.com/article",
    params={
        "formats": ["markdown", "html"],
        "onlyMainContent": True
    }
)

# Access markdown content
markdown = result.get("markdown")
print(markdown)

複数ページのクロール

import os
from firecrawl import FirecrawlApp

app = FirecrawlApp(api_key=os.environ.get("FIRECRAWL_API_KEY"))

# Start crawl
crawl_result = app.crawl_url(
    url="https://docs.example.com",
    params={
        "limit": 100,
        "scrapeOptions": {
            "formats": ["markdown"]
        }
    },
    poll_interval=5  # Check status every 5 seconds
)

# Process results
for page in crawl_result.get("data", []):
    url = page.get("url")
    markdown = page.get("markdown")
    print(f"Scraped: {url}")

構造化データの抽出

import os
from firecrawl import FirecrawlApp

app = FirecrawlApp(api_key=os.environ.get("FIRECRAWL_API_KEY"))

# Define schema
schema = {
    "type": "object",
    "properties": {
        "company_name": {"type": "string"},
        "product_price": {"type": "number"},
        "availability": {"type": "string"}
    },
    "required": ["company_name", "product_price"]
}

# Extract data
result = app.extract(
    urls=["https://example.com/product"],
    params={
        "schema": schema,
        "systemPrompt": "Extract product information from the page"
    }
)

print(result)

---

TypeScript/Node.js SDK の使用方法

インストール

npm install @mendable/firecrawl-js
# or
pnpm add @mendable/firecrawl-js
# or use the unscoped package:
npm install firecrawl

最新バージョン: @mendable/firecrawl-js v4.4.1+（または firecrawl v4.4.1+）

基本的なスクレイピング

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

// Initialize client
const app = new FirecrawlApp({
  apiKey: process.env.FIRECRAWL_API_KEY
});

// Scrape a single page
const result = await app.scrapeUrl('https://example.com/article', {
  formats: ['markdown', 'html'],
  onlyMainContent: true
});

// Access markdown content
const markdown = result.markdown;
console.log(markdown);

複数ページのクロール

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

const app = new FirecrawlApp({
  apiKey: process.env.FIRECRAWL_API_KEY
});

// Start crawl
const crawlResult = await app.crawlUrl('https://docs.example.com', {
  limit: 100,
  scrapeOptions: {
    formats: ['markdown']
  }
});

// Process results
for (const page of crawlResult.data) {
  console.log(`Scraped: ${page.url}`);
  console.log(page.markdown);
}

Zod を使用した構造化データの抽出

import FirecrawlApp from '@mendable/firecrawl-js';
import { z } from 'zod';

const app = new FirecrawlApp({
  apiKey: process.env.FIRECRAWL_API_KEY
});

// Define schema with Zod
const schema = z.object({
  company_name: z.string(),
  product_price: z.number(),
  availability: z.string()
});

// Extract data
const result = await app.extract({
  urls: ['https://example.com/product'],
  schema: schema,
  systemPrompt: 'Extract product information from the page'
});

console.log(result);

---

よくあるユースケース

1. ドキュメントのスクレイピング

シナリオ: RAG／チャットボット用にドキュメントサイト全体を Markdown に変換する

app = FirecrawlApp(api_key=os.environ.get("FIRECRAWL_API_KEY"))

docs = app.crawl_url(
    url="https://docs.myapi.com",
    params={
        "limit": 500,
        "scrapeOptions": {
            "formats": ["markdown"],
            "onlyMainContent": True
        },
        "allowedDomains": ["docs.myapi.com"]
    }
)

# Save to files
for page in docs.get("data", []):
    filename = page["url"].replace("https://", "").replace("/", "_") + ".md"
    with open(f"docs/{filename}", "w") as f:
        f.write(page["markdown"])

2. 製品データの抽出

シナリオ: e コマース用に構造化された製品データを抽出する

const schema = z.object({
  title: z.string(),
  price: z.number(),
  description: z.string(),
  images: z.array(z.string()),
  in_stock: z.boolean()
});

const products = await app.extract({
  urls: productUrls,
  schema: schema,
  systemPrompt: 'Extract all product details including price and availability'
});

3. ニュース記事のスクレイピング

シナリオ: 広告やナビゲーションを除いて、クリーンな記事コンテンツを抽出する

article = app.scrape_url(
    url="https://news.com/article",
    params={
        "formats": ["markdown"],
        "onlyMainContent": True,
        "removeBase64Images": True
    }
)

# Get clean markdown
content = article.get("markdown")

---

エラー処理

Python

from firecrawl import FirecrawlApp
from firecrawl.exceptions import FirecrawlException

app = FirecrawlApp(api_key=os.environ.get("FIRECRAWL_API_KEY"))

try:
    result = app.scrape_url("https://example.com")
except FirecrawlException as e:
    print(f"Firecrawl error: {e}")
except Exception as e:
    print(f"Unexpected error: {e}")

TypeScript

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

const app = new FirecrawlApp({
  apiKey: process.env.FIRECRAWL_API_KEY
});

try {
  const result = await app.scrapeUrl('https://example.com');
} catch (error) {
  if (error.response) {
    // API error
    console.error('API Error:', error.response.data);
  } else {
    // Network or other error
    console.error('Error:', error.message);
  }
}

---

レート制限とベストプラクティス

レート制限

• 無料プラン: 月あたり 500 クレジット
• 有料プラン: プランに応じて上限が増えます
• 消費クレジット数はエンドポイントとオプションによって異なります

ベストプラクティス

1. クレジット消費を抑え、よりクリーンなデータを取得するために、onlyMainContent: true を使用する
2. 過剰なコストを避けるため、クロールの上限を適切に設定する
3. 一時的なエラーには、指数バックオフを使用してリトライする
4. 同じコンテンツを再度スクレイピングしないよう、結果をローカルにキャッシュする
5. クロール戦略を計画するため、最初に map エンドポイントを使用する
6. 複数の URL を処理する場合は、抽出リクエストをまとめて送信する
7. ダッシュボードでクレジット使用量を監視する

---

Cloudflare Workers との統合

⚠️ 重要：SDK の互換性

Firecrawl SDK は Node.js の依存関係（特に Node.js の http モジュールを使用する axios）により、Cloudflare Workers では実行できません。 Workers では Web 標準 API が必要です。

✅ 代わりに、以下の例のように fetch を使って REST API を直接利用してください。

代替方法：workers-firecrawl を使ってセルフホストします。これは Workers ネイティブの実装です（Workers Paid Plan が必要で、/search エンドポイントのみを実装しています）。

---

Workers の例：REST API を直接利用する

この例では fetch API を使って Firecrawl を直接呼び出します。Cloudflare Workers で問題なく動作します。

interface Env {
  FIRECRAWL_API_KEY: string;
  SCRAPED_CACHE?: KVNamespace; // Optional: for caching results
}

interface FirecrawlScrapeResponse {
  success: boolean;
  data: {
    markdown?: string;
    html?: string;
    metadata: {
      title?: string;
      description?: string;
      language?: string;
      sourceURL: string;
    };
  };
}

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    if (request.method !== 'POST') {
      return Response.json({ error: 'Method not allowed' }, { status: 405 });
    }

    try {
      const { url } = await request.json<{ url: string }>();

      if (!url) {
        return Response.json({ error: 'URL is required' }, { status: 400 });
      }

      // Check cache (optional)
      if (env.SCRAPED_CACHE) {
        const cached = await env.SCRAPED_CACHE.get(url, 'json');
        if (cached) {
          return Response.json({ cached: true, data: cached });
        }
      }

      // Call Firecrawl API directly using fetch
      const response = await fetch('https://api.firecrawl.dev/v2/scrape', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${env.FIRECRAWL_API_KEY}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          url: url,
          formats: ['markdown'],
          onlyMainContent: true,
          removeBase64Images: true
        })
      });

      if (!response.ok) {
        const errorText = await response.text();
        throw new Error(`Firecrawl API error (${response.status}): ${errorText}`);
      }

      const result = await response.json<FirecrawlScrapeResponse>();

      // Cache for 1 hour (optional)
      if (env.SCRAPED_CACHE && result.success) {
        await env.SCRAPED_CACHE.put(
          url,
          JSON.stringify(result.data),
          { expirationTtl: 3600 }
        );
      }

      return Response.json({
        cached: false,
        data: result.data
      });

    } catch (error) {
      console.error('Scraping error:', error);
      return Response.json(
        { error: error instanceof Error ? error.message : 'Unknown error' },
        { status: 500 }
      );
    }
  }
};

環境の設定：Wrangler のシークレットに FIRECRAWL_API_KEY を追加します。

npx wrangler secret put FIRECRAWL_API_KEY

KV バインディング（任意）（キャッシュ用。wrangler.jsonc に追加します）：

{
  "kv_namespaces": [
    {
      "binding": "SCRAPED_CACHE",
      "id": "your-kv-namespace-id"
    }
  ]
}

本番環境ですぐに使える完全な例については、templates/firecrawl-worker-fetch.ts を参照してください。

---

このスキルを使う場面

✅ 次の場合は Firecrawl を使います：

• JavaScript を使用する最新のウェブサイトをスクレイピングする場合
• LLM 向けのクリーンな Markdown 出力が必要な場合
• ウェブコンテンツをもとに RAG システムを構築する場合
• 大規模に構造化データを抽出する場合
• ボット対策に対応する場合
• 信頼性が高く、本番環境ですぐに使えるスクレイピングが必要な場合

❌ 次の場合は Firecrawl を使いません：

• シンプルな静的 HTML をスクレイピングする場合（cheerio／beautifulsoup を使います）
• 既存の Puppeteer／Playwright の設定が問題なく動作している場合
• API を扱う場合（代わりに API を直接呼び出します）
• 予算に制約がある場合（無料プランには制限があります）

---

よくある問題と解決策

問題：「Invalid API Key」

原因：API キーが設定されていないか、正しくありません
修正方法：

# Check env variable is set
echo $FIRECRAWL_API_KEY

# Verify key format (should start with fc-)

問題：「Rate limit exceeded」

原因：月間クレジットの上限を超過しています
修正方法：

• ダッシュボードで使用状況を確認します
• プランをアップグレードするか、リセットを待ちます
• onlyMainContent: true を使ってクレジットの消費を抑えます

問題：「Timeout error」

原因：ページの読み込みに時間がかかりすぎています
修正方法：

result = app.scrape_url(url, params={"waitFor": 10000})  # Wait 10s

問題：「Content is empty」

原因：初回のレンダリング後に JavaScript でコンテンツが読み込まれています
修正方法：

result = app.scrape_url(url, params={
    "waitFor": 5000,
    "actions": [{"type": "wait", "milliseconds": 3000}]
})

---

高度な機能

ブラウザー操作

スクレイピングの前に操作を実行します。

result = app.scrape_url(
    url="https://example.com",
    params={
        "actions": [
            {"type": "click", "selector": "button.load-more"},
            {"type": "wait", "milliseconds": 2000},
            {"type": "scroll", "direction": "down"}
        ]
    }
)

カスタムヘッダー

result = app.scrape_url(
    url="https://example.com",
    params={
        "headers": {
            "User-Agent": "Custom Bot 1.0",
            "Accept-Language": "en-US"
        }
    }
)

長時間のクロール向け Webhook

ポーリングの代わりに、Webhook で結果を受け取ります。

crawl = app.crawl_url(
    url="https://docs.example.com",
    params={
        "limit": 1000,
        "webhook": "https://your-domain.com/webhook"
    }
)

---

パッケージのバージョン

パッケージ	バージョン	最終確認日
firecrawl-py	4.5.0+	2025-10-20
@mendable/firecrawl-js (or firecrawl)	4.4.1+	2025-10-24
API Version	v2	Current

注：Node.js SDK には Node.js >=22.0.0 が必要で、Cloudflare Workers では実行できません。Workers では REST API を直接呼び出してください（Cloudflare Workers との統合のセクションを参照）。

---

公式ドキュメント

• ドキュメント：https://docs.firecrawl.dev
• Python SDK：https://docs.firecrawl.dev/sdks/python
• Node.js SDK：https://docs.firecrawl.dev/sdks/node
• API リファレンス：https://docs.firecrawl.dev/api-reference
• GitHub：https://github.com/mendableai/firecrawl
• ダッシュボード：https://www.firecrawl.dev/app

---

このスキルを使った後の次のステップ

1. スクレイピングしたデータを保存する：Cloudflare D1、R2、または KV を使って結果を永続化します
2. RAG システムを構築する：Vectorize と組み合わせてセマンティック検索を行います
3. スケジュールを追加する：Cloudflare Queues を使ってスクレイピングを定期実行します
4. コンテンツを処理する：Workers AI を使ってスクレイピングしたデータを分析します

---

トークン削減量：手動での統合と比べて約 60％
エラー防止：API 認証、レート制限、フォーマット処理
本番環境ですぐに利用可能：✅