music-podcast-research

音乐与播客研究

通过 Crawlora API 查询 Spotify、Spotify Podcasts、Apple Podcasts、Discogs 和 SoundCloud 上的曲目、专辑、艺人、播放列表及播客节目／单集，并获取规范化的 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）——请遍历各页以获取完整结果。