Spotify Web API ガイド：完全チュートリアル (2026年版)

Spotify Web API ガイド：コンプリートチュートリアル (2026)

Spotify Web API を使用すると、開発者は Spotify の膨大な音楽カタログ、ユーザーのプレイリスト、再生コントロール、オーディオ機能、およびレコメンデーションエンジンにアクセスできます。音楽発見アプリ、プレイリストジェネレーター、データ視覚化ツールの構築、あるいは既存製品への Spotify の統合など、このガイドでは開始に必要なすべてを網羅しています。

Spotify API で何が作れるのか？

ユースケース	使用されるエンドポイント
音楽の検索と発見	Search, Recommendations, Browse
プレイリストの作成と管理	Playlists, Tracks
ユーザープロフィールと視聴データ	User Profile, Top Items, Recently Played
オーディオ分析 (BPM, key, energy)	Audio Features, Audio Analysis
再生コントロール	Player (Premiumアカウントが必要)
アーティストとアルバムのデータ	Artists, Albums

はじめに

ステップ 1: Spotify Developer アカウントの作成

1. developer.spotify.com にアクセスします。
2. Spotify アカウントでログインします（無料プラン、Premium プランのどちらでも可能です）。
3. Dashboard に移動します。
4. Create App をクリックします。
5. アプリ名、説明、および Redirect URI を入力します（開発用には http://localhost:3000/callback を使用してください）。
6. Client ID と Client Secret をメモします。

ステップ 2: 認証フローを理解する

Spotify は、ユースケースに応じていくつかのフローを持つ OAuth 2.0 を使用します。

フロー	ユースケース	ユーザーログインの必要性	ユーザーデータへのアクセス
Client Credentials	サーバー間通信、公開データのみ	不要	不可
Authorization Code	ユーザーデータを必要とする Web アプリ	必要	可能
Authorization Code + PKCE	SPA およびモバイルアプリ	必要	可能
Implicit Grant	非推奨（使用しないでください）	必要	可能

ほとんどのアプリケーションでは、公開データ用には Client Credentials を、ユーザー固有のデータ用には Authorization Code + PKCE を使用します。

ステップ 3: SDK のインストール

Python:

pip install spotipy

Node.js:

npm install spotify-web-api-node

または、言語を問わず生の HTTP リクエストを使用することもできます。API は REST ベースです。

認証: Client Credentials Flow

公開データ（検索、アーティスト情報、アルバムのトラックなど）のみが必要で、ユーザーのプライベートデータにアクセスする必要がない場合は、このフローを使用します。

Spotipy を使用した Python

import spotipy
from spotipy.oauth2 import SpotifyClientCredentials

client_credentials_manager = SpotifyClientCredentials(
    client_id="your-client-id",
    client_secret="your-client-secret",
)

sp = spotipy.Spotify(client_credentials_manager=client_credentials_manager)

# トラックを検索
results = sp.search(q="artist:Radiohead", type="track", limit=10)

for track in results["tracks"]["items"]:
    print(f"{track['name']} - {track['album']['name']}")

Node.js

import SpotifyWebApi from "spotify-web-api-node";

const spotifyApi = new SpotifyWebApi({
  clientId: "your-client-id",
  clientSecret: "your-client-secret",
});

// アクセストークンの取得
const data = await spotifyApi.clientCredentialsGrant();
spotifyApi.setAccessToken(data.body["access_token"]);

// トラックを検索
const results = await spotifyApi.searchTracks("artist:Radiohead", { limit: 10 });

results.body.tracks.items.forEach((track) => {
  console.log(`${track.name} - ${track.album.name}`);
});

cURL

# アクセストークンの取得
TOKEN=$(curl -s -X POST https://accounts.spotify.com/api/token \
  -u "your-client-id:your-client-secret" \
  -d "grant_type=client_credentials" | jq -r '.access_token')

# トラックを検索
curl -s "https://api.spotify.com/v1/search?q=artist:Radiohead&type=track&limit=5" \
  -H "Authorization: Bearer $TOKEN" | jq '.tracks.items[] | {name, album: .album.name}'

認証: Authorization Code Flow with PKCE

プレイリスト、トップトラック、再生コントロールなどのユーザー固有のデータにアクセスする必要がある場合は、このフローを使用します。

Flask を使用した Python の例

import spotipy
from spotipy.oauth2 import SpotifyOAuth
from flask import Flask, redirect, request, session

app = Flask(__name__)
app.secret_key = "your-secret-key"

SCOPE = "user-read-recently-played user-top-read playlist-modify-public"

@app.route("/login")
def login():
    sp_oauth = SpotifyOAuth(
        client_id="your-client-id",
        client_secret="your-client-secret",
        redirect_uri="http://localhost:3000/callback",
        scope=SCOPE,
    )
    auth_url = sp_oauth.get_authorize_url()
    return redirect(auth_url)

@app.route("/callback")
def callback():
    sp_oauth = SpotifyOAuth(
        client_id="your-client-id",
        client_secret="your-client-secret",
        redirect_uri="http://localhost:3000/callback",
        scope=SCOPE,
    )
    code = request.args.get("code")
    token_info = sp_oauth.get_access_token(code)
    session["token_info"] = token_info
    return redirect("/top-tracks")

@app.route("/top-tracks")
def top_tracks():
    token_info = session.get("token_info")
    sp = spotipy.Spotify(auth=token_info["access_token"])

    results = sp.current_user_top_tracks(limit=20, time_range="medium_term")

    tracks = []
    for track in results["items"]:
        tracks.append(f"{track['name']} by {track['artists'][0]['name']}")

    return "<br>".join(tracks)

一般的な API エンドポイント

Search

トラック、アーティスト、アルバム、プレイリスト、ポッドキャストを横断して検索します。

# トラックを検索
results = sp.search(q="genre:electronic year:2025-2026", type="track", limit=20)

# アーティストを検索
results = sp.search(q="Daft Punk", type="artist", limit=5)

# 複数のタイプを指定して検索
results = sp.search(q="jazz", type="track,artist,album", limit=10)

Audio Features の取得

Audio Features は、トラックの音楽的属性を提供します。

# 単一のトラックのオーディオ機能を取得
features = sp.audio_features("track-id-here")[0]

print(f"BPM: {features['tempo']}")
print(f"Key: {features['key']}")
print(f"Energy: {features['energy']}")
print(f"Danceability: {features['danceability']}")
print(f"Valence (mood): {features['valence']}")

オーディオ機能の値とその意味：

特徴 (Feature)	範囲	低い値の意味	高い値の意味
energy	0.0-1.0	穏やか、静か	うるさい、強烈
danceability	0.0-1.0	踊りにくい	踊りやすい
valence	0.0-1.0	悲しい、怒り	幸せ、陽気
tempo	BPM	遅い	速い
acousticness	0.0-1.0	電子的	アコースティック
instrumentalness	0.0-1.0	ボーカルあり	インストゥルメンタル
speechiness	0.0-1.0	音楽	話し言葉

Recommendations の取得

シードとなるトラック、アーティスト、ジャンルを使用してレコメンデーションエンジンを構築します。

# シードトラックとターゲットオーディオ機能に基づいたレコメンデーションの取得
recommendations = sp.recommendations(
    seed_tracks=["track-id-1", "track-id-2"],
    seed_genres=["electronic"],
    limit=20,
    target_energy=0.8,
    target_danceability=0.7,
    min_tempo=120,
    max_tempo=140,
)

for track in recommendations["tracks"]:
    print(f"{track['name']} by {track['artists'][0]['name']}")

Playlists の管理

プレイリストの作成、読み取り、更新を行います。

# 新しいプレイリストを作成
playlist = sp.user_playlist_create(
    user=sp.current_user()["id"],
    name="My AI-Generated Playlist",
    public=True,
    description="Created with the Spotify API",
)

# プレイリストにトラックを追加
track_uris = ["spotify:track:id1", "spotify:track:id2", "spotify:track:id3"]
sp.playlist_add_items(playlist["id"], track_uris)

# プレイリストのトラックを取得
tracks = sp.playlist_tracks("playlist-id")
for item in tracks["items"]:
    track = item["track"]
    print(f"{track['name']} by {track['artists'][0]['name']}")

Playback Control (Premium が必要)

# 現在再生中のトラックを取得
current = sp.current_playback()
if current and current["is_playing"]:
    track = current["item"]
    print(f"Now playing: {track['name']} by {track['artists'][0]['name']}")

# 次のトラックにスキップ
sp.next_track()

# 音量を設定
sp.volume(75)

# 特定のデバイスで再生を開始
devices = sp.devices()
device_id = devices["devices"][0]["id"]
sp.start_playback(device_id=device_id, uris=["spotify:track:track-id"])

プレイリストジェネレーターの構築

以下は、気分（mood）パラメータに基づいてプレイリストを作成する完全な例です。

import spotipy
from spotipy.oauth2 import SpotifyOAuth

MOOD_PRESETS = {
    "workout": {
        "seed_genres": ["electronic", "hip-hop"],
        "target_energy": 0.9,
        "target_danceability": 0.8,
        "min_tempo": 130,
    },
    "chill": {
        "seed_genres": ["ambient", "chill"],
        "target_energy": 0.3,
        "target_valence": 0.4,
        "max_tempo": 100,
    },
    "focus": {
        "seed_genres": ["classical", "ambient"],
        "target_instrumentalness": 0.8,
        "target_energy": 0.4,
        "target_speechiness": 0.0,
    },
    "party": {
        "seed_genres": ["pop", "dance"],
        "target_energy": 0.85,
        "target_danceability": 0.9,
        "target_valence": 0.8,
    },
}


def create_mood_playlist(sp, mood, num_tracks=25):
    if mood not in MOOD_PRESETS:
        raise ValueError(f"Unknown mood: {mood}. Options: {list(MOOD_PRESETS.keys())}")

    params = MOOD_PRESETS[mood]
    recommendations = sp.recommendations(limit=num_tracks, **params)

    track_uris = [track["uri"] for track in recommendations["tracks"]]

    user_id = sp.current_user()["id"]
    playlist = sp.user_playlist_create(
        user=user_id,
        name=f"{mood.capitalize()} Mix - AI Generated",
        description=f"A {mood} playlist generated with the Spotify API.",
    )

    sp.playlist_add_items(playlist["id"], track_uris)

    return playlist["external_urls"]["spotify"]


# 使用例
sp = spotipy.Spotify(auth_manager=SpotifyOAuth(
    client_id="your-client-id",
    client_secret="your-client-secret",
    redirect_uri="http://localhost:3000/callback",
    scope="playlist-modify-public",
))

url = create_mood_playlist(sp, "workout")
print(f"Playlist created: {url}")

回数制限（Rate Limits）とベストプラクティス

Rate Limits

Spotify はスライディングウィンドウ方式のレートリミットを使用しています。正確な制限は公開されていませんが、一般的なガイドラインは以下の通りです。

ガイドライン	推奨事項
秒間リクエスト数	ほとんどのエンドポイントで 10 未満に抑える
バッチエンドポイント	バッチ版を使用する（例：1 回の呼び出しで複数のトラックを取得）
429 エラー時の再試行	Retry-After ヘッダーを尊重する
トークンのリフレッシュ	有効期限（1 時間）が切れる前にリフレッシュする

エラーハンドリング

from spotipy.exceptions import SpotifyException
import time

def safe_request(func, *args, max_retries=3, **kwargs):
    for attempt in range(max_retries):
        try:
            return func(*args, **kwargs)
        except SpotifyException as e:
            if e.http_status == 429:
                retry_after = int(e.headers.get("Retry-After", 5))
                print(f"Rate limited. Waiting {retry_after}s...")
                time.sleep(retry_after)
            elif e.http_status == 401:
                print("Token expired. Refreshing...")
                # トークンリフレッシュの処理
                raise
            else:
                raise

    raise Exception("Max retries exceeded")

ページネーション

多くの Spotify エンドポイントはページ分けされた結果を返します。完全なデータを取得するために、常にページネーションを処理してください。

def get_all_playlist_tracks(sp, playlist_id):
    tracks = []
    results = sp.playlist_tracks(playlist_id, limit=100)

    while results:
        tracks.extend(results["items"])
        results = sp.next(results) if results["next"] else None

    return tracks

利用可能な OAuth スコープ（Scopes）

スコープ	アクセス権限
user-read-private	ユーザーのサブスクリプション詳細と国
user-read-email	ユーザーのメールアドレス
user-top-read	ユーザーのトップアーティストとトラック
user-read-recently-played	ユーザーの最近再生したトラック
playlist-read-private	ユーザーの非公開プレイリスト
playlist-modify-public	公開プレイリストの作成と編集
playlist-modify-private	非公開プレイリストの作成と編集
user-read-playback-state	現在の再生状態
user-modify-playback-state	再生コントロール（Premium のみ）
user-library-read	ユーザーのお気に入りトラックとアルバム
user-library-modify	トラックとアルバムの保存と削除

アプリケーションに必要なスコープのみをリクエストしてください。ユーザーは認証中に要求された権限を確認し、多すぎる場合は拒否する可能性があります。

まとめ

Spotify Web API は、最もドキュメントが充実しており、開発者に優しい音楽 API の 1 つです。シンプルなプレイリストジェネレーターから複雑な音楽分析プラットフォームまで、検索、レコメンデーション、オーディオ機能、およびユーザーデータの組み合わせは豊かな基盤を提供します。

音楽と AI 生成メディアを組み合わせたアプリケーション（視覚化の作成、トーキングアバター動画、AI 生成のアルバムアートなど）を構築している場合は、Hypereal AI をチェックしてください。Hypereal は、画像生成、ビデオ作成、およびトーキングアバターのための統合 API を従量課金制で提供しています。