music-podcast-research

音楽・ポッドキャストの調査

Spotify、Spotify Podcasts、Apple Podcasts、Discogs、SoundCloudでトラック、アルバム、アーティスト、プレイリスト、ポッドキャスト番組・エピソードを検索し、Crawlora APIから正規化されたJSONを取得します。ストリーミングアプリのページをスクレイピングする必要はありません。

このスキルを使う場面

• 「Spotifyでこのトラック／アルバム／アーティストを探して」／「このプレイリストには何が入っている？」
• 「Spotifyユーザーの公開プロフィール／プレイリストを調べて」
• 「人気のポッドキャスト／エピソードは？」（Spotify Podcasts、Apple Podcastsのチャート）
• 「このポッドキャスト番組／エピソードの詳細を取得して」
• 「このレコードにはどんなプレス盤／リリースがある？」（Discogs — レコード・コレクター向けデータ）
• 「このSoundCloudのトラック／ユーザーを調べて」／「このトラックの再生数／いいね数は？」／「このアーティストがSoundCloudにアップロードしたものは？」

セットアップ（一度のみ）

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

仕組み

1. Spotify — まず検索します。/spotify/search（または対象を絞った/spotify/tracks/search、/spotify/artists/search、/spotify/albums/search、/spotify/playlists/search、/spotify/profiles/search）にqを指定します。詳細エンドポイント（/spotify/track、/spotify/album、/spotify/artist、/spotify/playlist、/spotify/profile）では、idまたはuri（spotify:track:...のようなSpotify URI）のどちらかを指定できます。手元にある方を渡してください。/spotify/artist/related、/spotify/track/recommended、/spotify/track/similar-albumsを使って新しい音楽を探せます。
2. Spotify Podcasts — /spotify-podcasts/search、/spotify-podcasts/show（uriで指定）、/spotify-podcasts/show/episodes、/spotify-podcasts/charts。
3. Apple Podcasts — /apple-podcasts/search（term）、/apple-podcasts/show/{id}、/apple-podcasts/show/{id}/episodes、国別の人気ランキングを調べる/apple-podcasts/charts／/apple-podcasts/charts/rankings。
4. Discogs — /discogs/search（q、任意のtype = release/master/artist/label）でIDを探し、その後、詳細を/discogs/release/{id}、/discogs/master/{id}、/discogs/artist/{id}、/discogs/label/{id}で取得します（アーティスト／レーベルのカタログには/releasesのサブパスも使えます）。
5. SoundCloud — /soundcloud/search（query）でトラックを探し、その後、/soundcloud/track（url — トラックの完全なpermalink_url）で詳細なメタデータと再生数／いいね数／コメント数／リポスト数を取得します。/soundcloud/profile（url — ユーザーのプロフィールURL）では、プロフィール紹介文とフォロワー数／トラック数を取得できます。/soundcloud/user-tracks（url）では、そのユーザー自身のアップロードを一覧表示します。/soundcloud/playlist（url）では、プレイリスト／アルバムのメタデータと全トラックリストを取得します。

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

APIの呼び出し

# Spotify:
scripts/crawlora.sh /spotify/search q="Daft Punk" | jq '.'
scripts/crawlora.sh /spotify/artist id=4tZwfgrHOc3mvqYlEYSvVi | jq '.'

# Podcasts:
scripts/crawlora.sh /apple-podcasts/search term="Reply All" | jq '.'
scripts/crawlora.sh /spotify-podcasts/charts | jq '.'

# Discogs:
scripts/crawlora.sh /discogs/search q="Random Access Memories" type=release | jq '.'
scripts/crawlora.sh /discogs/release/4818226 | jq '.'

# SoundCloud:
scripts/crawlora.sh /soundcloud/search query="lofi hip hop" | jq '.'
scripts/crawlora.sh /soundcloud/track url="https://soundcloud.com/artist/track-name" | jq '.'

すべてのリクエストにはscripts/crawlora.shを使用してください。APIキーがコマンドライン引数に含まれないようにできます。

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

このスキルで使用するSpotify、Spotify Podcasts、Apple Podcasts、Discogs、SoundCloudの全エンドポイントについては、reference/endpoints.mdを参照してください。

例

• アーティストの詳細調査： 完全なディスコグラフィーと類似アーティストの一覧を調べるには、/spotify/artist、/spotify/artist/albums、/spotify/artist/relatedを使用します。
• ポッドキャストの検索： 人気の番組を見つけるには/spotify-podcasts/chartsまたは/apple-podcasts/chartsを使用し、その後、番組の過去のエピソード一覧を/spotify-podcasts/show/episodesで取得します。
• コレクター向けの調査： リリースを/discogs/searchで検索し、その後、プレス盤の詳細（フォーマット、年、レーベル、コンディションの判断に役立つメタデータ）を/discogs/release/{id}で取得します。
• SoundCloudのアーティストカタログ： ユーザーのフォロワー数／トラック数を/soundcloud/profileで確認し、その後、トラックごとの再生数／いいね数／コメント数／リポスト数とともに、そのユーザー自身のアップロードを/soundcloud/user-tracksで取得します。

注意事項と制限

• クレジット／成功時のみ課金： 2xx の場合にのみ課金されます。無料枠は月あたり2,000クレジットです。 https://crawlora.net でキーを取得してください。
• 公開データのみ — 公開カタログ／プロフィール／チャートページ。
• セキュリティ： キーは CRAWLORA_API_KEY にのみ保存してください。ハードコード、クエリパラメーターへの指定、コミットは行わないでください。
• Spotify の詳細エンドポイントには id または uri が必要です。名前しか分からない場合は、対応する .../search エンドポイントで先に解決してください。
• SoundCloud の詳細エンドポイントには完全な url（トラック／プレイリスト／ユーザーの permalink_url。例：https://soundcloud.com/artist/track-name）が必要です。数値 ID での検索には対応していないため、名前しか分からない場合は、まず /soundcloud/search の結果から URL を取得してください。
• 検索エンドポイントはページネーションに対応しています（limit／offset または page）。すべてのデータを取得するには、ページを順にたどってください。