crawlora

Crawlora — 構造化された公開ウェブデータ

Crawlora は、公開ウェブサイトをクリーンで正規化された JSON に変換するホスト型 API です。 現在の公開データカタログには、467 のプラットフォームグループにまたがる 3,509 個のツールが含まれており、このリポジトリにはインストール可能なリサーチスキルが 169 個収録されています。API キー 1 つで、付属のカタログにあるエンドポイント（検索エンジン、マーケットプレイス、ソーシャルおよび動画、金融および暗号資産、地図、アプリストア、メディア、レビュー）を利用できるため、ブラウザーやプロキシ、HTML パーサーを使わずに、エージェントが実際のデータを取得できます。

対象範囲、課金、ジョブの副作用

このスキルは、Crawlora のホスト型サードパーティ API を呼び出します。カタログには、広範な公開ウェブ検索や範囲を限定したクロールのルートのほか、通常の単発データ検索も含まれます。一部のルートでは、最初のリクエスト後も継続し、所有者に限定されたジョブのステータス、イベント、結果を保持する、永続的なリサーチジョブや範囲を限定したウェブクロールジョブが開始されます。リクエストが成功するとクレジットを消費する場合があります。POST /web/crawl には max_credits の上限が必要です。こうしたジョブを開始する前に、データソースの範囲、クレジット上限、ジョブの継続動作についてユーザーに明確に伝えてください。定期的または範囲の定まらない処理は開始しないでください。ユーザーが CRAWLORA_API_KEY を通じて提供した API キーのみを使用し、表示、保存、コミットは決して行わないでください。

アカウント使用状況、最近の IP、ウェブサイト監視の管理、汎用 URL スクレイピング、APK 分析、一括プロフィールデータセットの各エンドポイントは、このスキルの対象外です。これらの特化したワークフローには専用のスキルがあり、このヘルパーもこれらのパスを拒否します。

このスキルを使用する場面

ユーザーから、公開ウェブサイト上の最新データを求められた場合は Crawlora を使用してください。例：

• 「Amazon／eBay／Shopify での X の価格は？」
• 「この YouTube 動画の文字起こし／コメントを取得して。」
• 「最新の Google／Bing の検索結果を取得して……」または「Google Trends で今話題のものは？」
• 「この iOS／Android アプリのレビューと評価。」
• 「NVDA の Yahoo Finance の株価／財務情報」「CoinGecko の値上がり銘柄トップ。」
• 「……に関する TikTok／Instagram／Reddit の投稿」「……の Trustpilot のレビュー。」
• HTML のスクレイピングやクローラーの保守が代替手段となるあらゆるタスク。

インストール済みのものがあれば、より具体的な Crawlora スキル（例：product-price-research、youtube-research、app-review-mining、serp-keyword-research）を優先してください。この包括的なスキルは、それ以外のすべてを対象とします。

セットアップ（初回のみ）

• Crawlora の無料 API キー（月 2,000 クレジット、カード不要）をhttps://crawlora.netで取得します。

• ヘルパーと curl 呼び出しからキーを読み取れるよう、環境変数に設定します。

  export CRAWLORA_API_KEY
  

  ヘルパーを実行する前に、受け取ったキーを CRAWLORA_API_KEY に設定してください。

• すべてのリクエストは https://api.crawlora.net/api/v1 に送信され、環境変数の CRAWLORA_API_KEY がヘッダーに設定されます。キーがないか無効な場合は 401 が返されます。

動作の仕組み

1. エンドポイントを選びます。 reference/catalog.md を開きます。プラットフォームごとにまとめられたすべてのエンドポイントと、メソッド、パス、パラメーターが記載されています。ユーザーのタスクに合うプラットフォームグループを選び、次にエンドポイントを選びます。
2. scripts/crawlora.sh で呼び出します（以下を参照）。認証を処理し、JSON を出力します。
3. jq で JSON を解析して回答します。多くのエンドポイントはページ分けされたリストを返します。ドキュメントに記載があれば、page／count パラメーターを渡してください。

API の呼び出し

# GET with query params (key=value):
scripts/crawlora.sh /amazon/search k=laptop | jq '.'
scripts/crawlora.sh /google/suggest q="web scraping" | jq '.'
scripts/crawlora.sh /youtube/transcript/dQw4w9WgXcQ | jq '.'

# POST endpoints take a JSON body (note the -X POST):
scripts/crawlora.sh -X POST /google/search '{"keyword":"web scraping api","language":"en","country":"us"}' | jq '.'
scripts/crawlora.sh -X POST /google/trends/explore/interest-over-time '{"keywords":["bitcoin"]}' | jq '.'

すべてのリクエストには scripts/crawlora.sh を使用してください。API キーをコマンドライン引数に含めずに済みます。

カタログには、各エンドポイントの HTTP メソッドが記載されています。{id} などのパスパラメーターは URL に置き換え、GET パラメーターはクエリー文字列に、POST パラメーターは JSON 本文に指定します。

エンドポイントリファレンス

プラットフォームごとにまとめられたエンドポイントの完全な一覧（メソッド、パス、パラメーター、説明）は、reference/catalog.md を参照してください。

例

• 商品価格： scripts/crawlora.sh /amazon/search k="standing desk" → .data[].price を読み取り、掲載価格を比較します。
• YouTube の文字起こし： URL から動画 ID を解決し、scripts/crawlora.sh /youtube/transcript/<id> を実行して要約します。
• トレンドの確認： scripts/crawlora.sh -X POST /google/trends/explore/interest-over-time '{"keywords":["electric bikes"]}'。
• 金融： scripts/crawlora.sh /yahoo-finance/ticker/NVDA/quote（正確なパス／パラメーターについては、カタログの Yahoo Finance グループを参照してください）。

注意事項と制限

• クレジット／成功時のみ課金： 2xx レスポンスの場合にのみ課金され、失敗時は課金されません。 無料枠は月 2,000 クレジットです。https://crawlora.net でキーを取得してください。
• 長時間実行されるジョブ： /research/jobs と /web/crawl は、永続的に実行される処理を作成します。 max_credits でクロールのクレジットを制限し、必要な場合にのみポーリングし、ユーザーが不要になったジョブはキャンセルしてください。
• 公開データのみ。 Crawlora は公開されているウェブデータを返します。サードパーティのアカウント認証情報は使用しません。各データソースの利用規約とレート制限を遵守してください。
• セキュリティ： キーは CRAWLORA_API_KEY にのみ保存してください。ハードコードしたり、URL クエリパラメーターに含めたり、コミットしたりしないでください。
• 上流のサービスがチャレンジページを返すと、一部の検索エンドポイントは 503 を返します。再試行するか、別の検索プロバイダー（Google ↔ Bing ↔ Brave）に切り替えてください。