SpotifyScraper Documentation¶

The Ultimate Python Library for Spotify Data Extraction

Version 2.0.0 | © 2025 Ali Akhtari

Installation | Quick Start | API Reference | Examples | FAQ

Welcome to SpotifyScraper¶

SpotifyScraper is a powerful, modern Python library designed to extract data from Spotify's web player without requiring API credentials. Built for reliability, performance, and ease of use, it provides a comprehensive toolkit for accessing Spotify's vast music database.

Why SpotifyScraper?¶

• Zero Authentication: No API keys, no OAuth, no hassle
• Comprehensive Data: Extract tracks, albums, artists, playlists, and lyrics
• High Performance: Optimized for speed with intelligent caching
• Type Safe: Full type hints for better IDE support
• Battle Tested: Used in production by thousands of developers
• Active Development: Regular updates and community support

Perfect For¶

• Music Analytics: Analyze trends, popularity, and musical patterns
• Research Projects: Academic research on music data
• Personal Tools: Build your own music management systems
• Data Science: Create datasets for machine learning
• Content Creation: Generate playlists and music recommendations

Installation¶

Basic Installation¶

pip install spotifyscraper

Installation with Optional Features¶

# With Selenium support for complex scenarios
pip install "spotifyscraper[selenium]"

# With enhanced media handling
pip install "spotifyscraper[media]"

# All features
pip install "spotifyscraper[all]"

Development Installation¶

git clone https://github.com/AliAkhtari78/SpotifyScraper.git
cd SpotifyScraper
pip install -e ".[dev]"

Quick Start¶

Your First Script¶

from spotify_scraper import SpotifyClient

# Initialize the client
client = SpotifyClient()

# Extract track information
track_url = "https://open.spotify.com/track/6rqhFgbbKwnb9MLmUQDhG6"
track = client.get_track_info(track_url)

print(f"Track: {track.get('name', 'Unknown')}")
print(f"Artist: {(track.get('artists', [{}])[0].get('name', 'Unknown') if track.get('artists') else 'Unknown')}")
print(f"Duration: {track.get('duration_ms', 0) / 1000:.0f} seconds")

# Always close when done
client.close()

Download Media¶

# Download track preview
preview_path = client.download_preview_mp3(track_url, path="downloads/")
print(f"Preview saved to: {preview_path}")

# Download album cover
cover_path = client.download_cover(track_url, path="covers/")
print(f"Cover saved to: {cover_path}")

Documentation Overview¶

Getting Started¶

• Installation Guide - Detailed installation instructions
• Quick Start Tutorial - Get up and running in minutes
• Configuration - Configure SpotifyScraper for your needs

User Guide¶

• Basic Usage - Core functionality and common tasks
• Authentication - Access premium features with cookies
• Media Downloads - Download audio and images
• Error Handling - Handle errors gracefully

API Reference¶

• SpotifyClient - Main client class
• Extractors - Data extraction classes
• Media Handlers - Audio and image downloaders
• Exceptions - Error types and handling
• Utilities - Helper functions

Examples¶

• Quick Examples - Common use cases
• Advanced Patterns - Complex scenarios
• Real-World Projects - Complete applications
• CLI Usage - Command-line interface

Advanced Topics¶

• Performance Optimization - Speed up your scripts
• Scaling Guide - Handle large-scale extraction
• Custom Extractors - Extend functionality
• Architecture - Internal design

Resources¶

• FAQ - Frequently asked questions
• Troubleshooting - Common issues and solutions
• Migration Guide - Upgrading from v1.x
• Changelog - Version history

Key Features¶

Data Extraction¶

• Tracks: Title, artists, album, duration, preview URLs
• Albums: Full track listings, release dates, cover art
• Artists: Biography, top tracks, discography, monthly listeners
• Playlists: Complete track lists, descriptions, owner info
• Lyrics: Not available (requires OAuth authentication, not supported)

Media Handling¶

• Audio Preview: Download 30-second MP3 previews
• Cover Art: High-resolution album/playlist covers
• Metadata: Automatic ID3 tag embedding
• Batch Downloads: Efficient bulk operations

Advanced Features¶

• Smart Caching: Reduce API calls and improve speed
• Proxy Support: Route through proxy servers
• Rate Limiting: Automatic request throttling
• Error Recovery: Robust retry mechanisms

Supported Platforms¶

• Windows (10, 11) - Fully Supported
• macOS (10.15+) - Fully Supported
• Linux (Ubuntu, Debian, Fedora, etc.) - Fully Supported
• Python (3.8, 3.9, 3.10, 3.11, 3.12) - All Versions Supported

Community & Support¶

Get Help¶

• Documentation
• GitHub Discussions
• Issue Tracker

Contributing¶

• Contributing Guide
• Code of Conduct
• Development Setup

Important Notes¶

Limitations¶

SpotifyScraper uses Spotify's embed API to provide reliable, authentication-free access. This approach has some limitations:

• Album Names: Track objects may have empty album names (images are always available)
• Rate Limits: Spotify may rate limit excessive requests
• Regional Availability: Some content may be region-restricted

Legal Disclaimer¶

This library is for educational and personal use. Always respect Spotify's Terms of Service and copyright laws. Be mindful of rate limits and use the library responsibly.

What's Next?¶