はじめに

Spotify APIはドキュメントで明文化されていない仕様があったり、アプリで存在する機能がAPIでは提供されてないといったことがよくあります。
そこで、Spotify APIの仕様についてメモしてみました。

Web API Reference(公式APIリファレンス)に記載されているエンドポイントごとに下記にまとめていきます。

2022年12月現在の情報のため、更新があれば修正します。
(誤りなどありましたら編集リクエスト、コメントなどいただけるとありがたいです。)

Follow

プレイリストのアンフォロー

プレイリスト自体のデータは削除できない

上記エンドポイントは自分で作成したプレイリストのアンフォローもできますが、プレイリストのデータそのものを削除することはできません。
例えば、自分で作成したプレイリストのフォロワーが自分のアカウントのみの場合（Spotifyの仕様上プレイリスト作成時点で自動的に作成したプレイリストのフォロワーになります）にアンフォローのエンドポイントからリクエストをすると、自分のアカウントも含めアプリ上からアクセスができなくなります。(ただし、プレイリストのURLから直接アクセスすることはできます。)

Player

ユーザーの再生状態の取得

停止状態から10分経過すると情報が取得できなくなる

ユーザーのプレイヤーが停止してから10分間何も操作しない状態が続くとステータスが 200から204に変わり、プレイヤーの情報が取得できなくなります。

ユーザーの再生の開始、停止

Spotifyアプリを起動（再生）している状態でないと機能しない

仕様というよりバグ？
デスクトップアプリの場合、アプリを起動した状態であればAPIは機能する。
スマホアプリの場合、アプリを起動し、かつ何らかの楽曲を再生している状態でないと500エラーとなる。

Playlists

プレイリスト情報の更新（プレイリスト名、公開状態、説明文）

説明文(description)を削除できない

プレイリストに説明文をつけることができるのですが、削除はできません。
リクエスト時にdescriptionを空で送るとAttribute description is emptyとエラーが出てしまいます。

Request_body.json

{
  "description": ""
}

対処法

全角スペースを入れることで一応文字が入らない状態を再現することができます。
半角スペースだとできません。

Request_body.json

{
  "description": "　"
}

プレイリスト画像の取得

プレイリスト画像の種類

プレイリスト画像には以下の種類があり、それぞれでドメインが異なります。

自動生成の画像（ジャケット画像1枚） https://i.scdn.co
自動生成の画像（ジャケット画像が４枚組になった画像）　https://mosaic.scdn.co
ユーザーが登録したプレイリスト画像 https://pl.scdn.co
チャート系（バイラル、トップチャート） https://charts-images.scdn.co
This is系 https://thisis-images.scdn.co
*一部例外あり

プレイリスト画像のアップロード

画像削除のAPIが存在しない

現状上記エンドポイントは以下の二点しかできません。

プレイリスト画像が登録されていない（デフォルト）状態からプレイリスト画像を設定する
プレイリスト画像が登録されている状態から別の画像に変更する
従って、プレイリスト画像をデフォルトの状態に戻す（削除）を行う操作は用意されていません。

Search

日本語で結果が返ってこない

例えば水曜日のカンパネラのような日本語で書かれているアーティストを検索した際、Wednesday Campanellaと変換されて結果が返ってきてしまいます。

対処法

その場合、Accept-Languageヘッダーをリクエスト時に付与することで日本語で結果が返ってきます。（公式ドキュメントに書いてほしい）
詳しくはこちらで書いてます。

ポッドキャストを検索する

ポッドキャストを検索する場合、typeをshowまたはepisodeを指定します。（両方指定することもできます）

https://api.spotify.com/v1/search?q=dan%20carlin&type=episode

https://api.spotify.com/v1/search?q=dan%20carlin&type=show

https://api.spotify.com/v1/search?q=dan%20carlin&type=episode,show

Tracks

トラック情報の取得

一部のトラックはプレビュー用のmp3が取得できない

試聴用に30秒のトラックのmp3が用意されていますが、権利関係などで一部のトラックは試聴用のmp3が取得できません。
取得できない場合、トラックオブジェクトのpreview_urlがnullで返されます。

Spotify APIの仕様についてまとめ