movie-tv-research

映画・テレビのリサーチ

Crawlora API から、7 つの映画・テレビデータソースにわたるタイトルのメタデータ、キャスト／スタッフ、評価、配信状況、レビュー、興行収入の数値を正規化された JSON として取得できます。IMDb のページをスクレイピングしたり、配信プロバイダーの HTML を解析したりする必要はありません。

このスキルを使う場面

• 「の出演者／監督は？」など、キャスト、スタッフ、クレジットを調べる場合。
• 「<title>のIMDb／Rotten Tomatoes／Metacritic／Letterboxdでの評価は？」
• 「はどこで配信されていますか？」（JustWatch ではプロバイダーごとの配信情報を確認できます）。
• 「<title>の興行成績は？」（Box Office Mojo）。
• 「に似た作品を探して」や「今人気の作品は？」
• 批評家と観客のレビューを比較する場合、シリーズ／ジャンル別の興行収入を分析する場合。

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

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

仕組み

用途に応じてソースを選びます。

1. 作品の特定とクレジット（IMDb／TMDB） — まず /imdb/search または /tmdb/search で検索し、その後、作品詳細を取得します。IMDb では /imdb/title（IMDb ID が必要）、TMDB では /tmdb/movie/{id} または /tmdb/tv/{id} を使います。キャスト／スタッフは /imdb/title/credits または TMDB のタイトル情報から取得できます。人物ページは /imdb/name または /tmdb/person/{id} です。
2. スコアとレビュー — Rotten Tomatoes（/rottentomatoes/movie、/series、 /movie/reviews）、Metacritic（/metacritic/movie/{slug}、 /critic-reviews、/user-reviews）、IMDb（/imdb/title/reviews）、 Letterboxd（/letterboxd/film/{slug}、/reviews、/rating-histogram）。
3. 配信先（JustWatch） — /justwatch/search で検索して生の ID を取得し、その後 /justwatch/title/offers（または /title-by-id と /title/offers）で、プロバイダーごとのストリーミング／レンタル／購入リンクを取得します。おすすめは /justwatch/title/similar から取得できます。
4. 興行収入（Box Office Mojo） — 1 作品の興行収入データは /boxofficemojo/title または /release から取得できます。チャートは /weekend/domestic、/year/domestic、/year/worldwide、集計データは /franchise／/genre／/brand、2 作品の公開成績の直接比較は /showdown を使います。

エンドポイント、メソッド、パラメーターの一覧は reference/endpoints.md を参照してください。

API の呼び出し

# Identity + scores:
scripts/crawlora.sh /imdb/search query="Dune Part Two" | jq '.'
scripts/crawlora.sh /tmdb/search query="Dune Part Two" | jq '.'
scripts/crawlora.sh /rottentomatoes/search query="Dune Part Two" | jq '.'

# Streaming availability:
scripts/crawlora.sh /justwatch/search query="Dune Part Two" | jq '.'
scripts/crawlora.sh /justwatch/title/offers id=<raw-justwatch-id> | jq '.'

# Box office:
scripts/crawlora.sh /boxofficemojo/title id=<mojo-title-id> | jq '.'

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

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

このスキルで使用する IMDb、TMDB、JustWatch、Letterboxd、Rotten Tomatoes、Metacritic、Box Office Mojo のすべてのエンドポイントについては、reference/endpoints.mdを参照してください。

使用例

• 批評家と観客の評価差： /metacritic/movie/{slug}（批評家の Metascore とユーザースコア）と、同じ作品の /rottentomatoes/movie（Tomatometer と観客スコア）を比較します。
• 視聴先の一括取得： /justwatch/search → /justwatch/title/offers の順に呼び出し、プロバイダーごとのサブスクリプション／レンタル／購入の選択肢と価格をすべて一覧表示します。
• シリーズの興行収入の推移： /boxofficemojo/franchise で各作品の初週興行収入と累計興行収入を取得し、時系列順に並べます。
• 好みに合う作品の検索： /letterboxd/film/{slug}/similar または /tmdb/movie/{id}（TMDB にはおすすめ作品が含まれます）を使って、「これに似た作品」を探します。

注意事項と制限

• クレジット／成功時のみ課金： 2xx の場合にのみ課金されます。無料枠は月 2,000 クレジットです。 キーは https://crawlora.netで取得できます。
• 公開データのみ — 公開されている作品、レビュー、興行収入のページが対象です。
• セキュリティ： キーは CRAWLORA_API_KEY のみに保存してください。コードに直接記述したり、クエリパラメーターに含めたり、コミットしたりしないでください。
• JustWatch は独自の生の GraphQL ID を使用します（IMDb／TMDB の ID ではありません）。先に /justwatch/search または /justwatch/title/by-id で解決してください。
• 記載のあるエンドポイントでは結果がページ分割されています。長い一覧（レビュー、チャート、フィルモグラフィー）を取得するには page を指定してください。