crawlora-datasets

Crawlora ホステッドデータセット

Crawlora が独自に事前クロール・事前インデックス化したデータセットを検索します。Crawlora がすでに構築し、スケジュールに従って更新しているコーパスに対して、検索、ファセット検索、ID による取得ができます。 このリポジトリのほかのスキルとは異なり、ほかのスキルはプラットフォームごとのライブエンドポイントを呼び出します（1 回のリクエストで 1 ページ）。このスキルは、すでに収集された数百万件のレコードを対象とする検索インデックスを利用するため、単発の検索ではなく、母集団全体に関する質問（「いくつあるか」「X 別の上位 N 件」「Y に該当するすべて」）に適しています。

このスキルを使う場面

• 「X のうち Y に該当するのはいくつか／何割か？」— ファセット／集計に関する質問。
• 「Y の条件を満たす X をすべて見つけて」（例：給与が 15 万ドルを超える求人、評価が 4.5 以上のアプリ、都市近郊の GitHub ユーザー、大都市圏の住宅）。
• 1 件のレコードではなく、「Z の完全な一覧をください」— 一括／リスト調査。
• 次のいずれか：Airbnb の市場、アプリストアのアプリ／レビュー／ランキング、GitHub／Instagram／X のユーザー、求人情報と採用中の企業、米国の住宅市場（Redfin 提供）、Google Maps のビジネス、Goodreads の著者／書籍、Apple Podcasts の番組、Chrome Web Store の拡張機能、PitchBook の企業／ファンド／投資家／アドバイザー／LP、PlayStation のゲーム、Product Hunt のメーカー／製品／トレンド、Reddit のトレンド、SEC の企業と機関投資家の保有状況、Steam のゲーム／価格／プレイヤー数／レビュー／ニュース／実績／ランキング、TrustMRR のスタートアップ、ジャーナリスト、Numbeo の生活費に関する都市／国、ウェブサイトの技術スタック。
• 依頼が「今すぐ、この 1 件のプロフィール／リスティングを調べる」場合（例：youtube-research、movie-tv-research）は、代わりにプラットフォーム固有のスキルを優先してください。データセットは定期的に更新されるものであり、リアルタイムではありません。

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

• Crawlora API キーを無料で取得します（月 2,000 クレジット、カード不要）。https://crawlora.net にアクセスしてください。
• ヘルパーを実行する前に、環境変数に CRAWLORA_API_KEY を設定します。
• ヘルパーは環境変数から CRAWLORA_API_KEY を読み込み、https://api.crawlora.net/api/v1 にリクエストを送信します。キーがない、または無効な場合は 401 が返されます。

仕組み

すべてのデータセットで、/datasets/<dataset-id>/... 以下のエンドポイント構成は同じです。

1. 検出 — GET /datasets は、利用可能なすべてのデータセット ID と、それぞれの機能（検索／ファセット／アイテム／近隣検索）を一覧表示します。
2. 検索 — GET /datasets/<id>/search は、全文検索とフィルター検索を行います。page／size でページ分割します（データセットごとの詳細は reference/endpoints.md を参照）。
3. ファセット — GET /datasets/<id>/facets は、データセット内のファセット検索が可能なフィールドについて、集計結果をまとめて返します（例：求人データセットでは、上位の企業、部門、勤務地、職位、リモート勤務の割合などが 1 回の呼び出しで返されます）。「いくつあるか／X 別の内訳は？」という質問に使います。
4. アイテム — GET /datasets/<id>/items/{id} は、データセットキー（データセットごとに異なります。login、username、slug、cik、appid、domain、region_type/table_id など）で 1 件のレコードを取得します。
5. 近隣検索 — 対応している場合（airbnb-markets、github-users、google-map-businesses、jobs）、GET /datasets/<id>/nearby は、lat／lon の地点から radius_km 以内にあるレコードを検索します。

すべてのエンドポイント、データセットごとの ID、パラメーターについては、reference/endpoints.md を参照してください。

API の呼び出し

# List every dataset id and what it supports:
scripts/crawlora.sh /datasets | jq '.'

# Search the jobs dataset (all companies' live postings):
scripts/crawlora.sh /datasets/jobs/search q="staff engineer" location="remote" | jq '.'

# Facet: hiring-market breakdown (top companies, seniority, remote share, ...):
scripts/crawlora.sh /datasets/jobs/facets | jq '.'

# Item: one GitHub user by login:
scripts/crawlora.sh /datasets/github-users/items/torvalds | jq '.'

# Nearby: GitHub users within 50km of a coordinate (radius in meters):
scripts/crawlora.sh /datasets/github-users/nearby lat=37.7749 lon=-122.4194 radius_m=50000 | jq '.'

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

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

すべてのデータセット ID、検索／ファセット／アイテム／近隣検索の各エンドポイント、およびパラメーターについては、reference/endpoints.md を参照してください。

使用例

• 採用市場の動向把握： 集計の内訳（上位企業、職位、リモート勤務の割合）には /datasets/jobs/facets を使用し、次に /datasets/jobs/companies で積極的に求人を掲載している雇用主を確認します。
• アプリストアの全体像の調査： カテゴリと評価で絞り込んだ /datasets/apps/search を使用し、次に /datasets/apps-reviews/search で上位の検索結果の背景にある感情を確認します。
• スタートアップの収益ランキング： MRR で並べ替えた /datasets/trustmrr/search を使用し、次に /datasets/trustmrr/history/{slug} で特定企業の推移を確認します。
• 住宅市場のスナップショット： 都市圏には /datasets/housing-markets/search を使用し、次に /datasets/housing-markets/items/{region_type}/{table_id} で月ごとの全データを確認します。

注意事項と制限

• クレジット／成功時のみ課金： 2xx の場合にのみ課金されます。無料枠は月 2,000 クレジットです。 キーは https://crawlora.net で取得してください。
• 公開データのみ — すべてのデータセットは公開ソースから構築されています。
• セキュリティ： キーは CRAWLORA_API_KEY のみに保存してください。ハードコード、クエリパラメーターへの追加、コミットはしないでください。
• データセットはスケジュールに従って更新されます（ソースに応じて毎日／毎週）。リアルタイムではありません。単一レコードをライブで検索する場合は、代わりにこのリポジトリ内の該当するプラットフォーム固有のスキル（例：job-market-research、movie-tv-research）を使用してください。
• 結果はページ分割されています（page／size）。すべてのデータを取得するには、各ページを順に確認してください。