Caution

As of 2024-11-28, most streams are currently broken due to sudden breaking changes in the Spotify Web API - tracked in #116

tap-spotify

tap-spotify is a Singer tap for Spotify.

Built with the Meltano Tap SDK for Singer Taps.

Overview

tap-spotify extracts raw data from the Spotify Web API for the following resources:

• User's top tracks
• User's top artists
• User's saved tracks
• Global top 50 tracks (daily)
• Global top 50 tracks (weekly)
• Viral top 50 tracks (daily)

Installation

# pip
pip install git+https://github.com/Matatika/tap-spotify

# pipx
pipx install git+https://github.com/Matatika/tap-spotify

# poetry
poetry add git+https://github.com/Matatika/tap-spotify

Configuration

Accepted Config Options

Name	Required	Default	Description
client_id	Yes		Your tap-spotify app client ID
client_secret	Yes		Your tap-spotify app client secret
refresh_token	Yes		Your tap-spotify app refresh token

A full list of supported settings and capabilities for this tap is available by running:

tap-spotify --about

Source Authentication and Authorization

Before using tap-spotify, you will need to create an app from your Spotify developer dashboard. We recommend restricting your use of this app to tap-spotify only. Provide an name, description and a redirect URI of https://matatika.github.io/spotify-refresh-token (explained below).

Get a Refresh Token

Use this web app to get a refresh token with your Spotify app credentials:

• Provide your app client ID and secret in the appropriate fields
• Click 'Submit' and follow the Spotify login flow
• Copy the refresh token

Credit to Alec Chen for the original project

Each stream requires certain token scopes. By default (all streams selected), the following token scopes are required:

• user-top-read
• user-library-read

When specific streams are selected, the required token scopes may change.

Stream	Required scope(s)
user_top_tracks_st_stream	user-top-read
user_top_tracks_mt_stream	user-top-read
user_top_tracks_lt_stream	user-top-read
user_top_artists_st_stream	user-top-read
user_top_artists_mt_stream	user-top-read
user_top_artists_lt_stream	user-top-read
global_top_tracks_daily_stream
global_top_tracks_weekly_stream
global_viral_tracks_daily_stream
user_saved_tracks_stream	user-library-read

If a required scope is not set, tap-spotify will encounter a 403 Forbidden response from the Spotify Web API and fail. You must set all required scopes for the selected streams.

Any other scopes not listed here are not required by tap-spotify. Setting these will allow applications using the same Spotify app credentials to read more specific and possibly sensitive resource data, so do this at your own risk.

Usage

You can easily run tap-spotify by itself or in a pipeline using Meltano.

Executing the Tap Directly

tap-spotify --version
tap-spotify --help
tap-spotify --config CONFIG --discover > ./catalog.json

Developer Resources

Initialize your Development Environment

pipx install poetry
make init

Lint your Code

make lint

Create and Run Tests

Create tests within the tap_spotify/tests subfolder and then run:

make test

You can also test the tap-spotify CLI interface directly using poetry run:

poetry run tap-spotify --help

Testing with Meltano

Note: This tap will work in any Singer environment and does not require Meltano. Examples here are for convenience and to streamline end-to-end orchestration scenarios.

Your project comes with a custom meltano.yml project file already created. Open the meltano.yml and follow any "TODO" items listed in the file.

Next, install Meltano (if you haven't already) and any needed plugins:

# Install meltano
pipx install meltano
# Initialize meltano within this directory
cd tap-spotify
meltano install

Now you can test and orchestrate using Meltano:

# Test invocation:
meltano invoke tap-spotify --version
# OR run a test `elt` pipeline:
meltano elt tap-spotify target-jsonl

SDK Dev Guide

See the dev guide for more instructions on how to use the SDK to develop your own taps and targets.