Getting Started¶

Welcome to SpotifyScraper - your gateway to effortless Spotify data extraction! This section will guide you from zero to hero, helping you understand, install, and configure SpotifyScraper for your projects.

What You'll Learn¶

Why SpotifyScraper?¶

🎯 Zero Authentication Required¶

Unlike the official Spotify API, SpotifyScraper doesn't require: - API keys or client secrets - OAuth authentication flows - App registration or approval - Rate limit management

🛠️ Simple Yet Powerful¶

# This is all you need to get started!
from spotify_scraper import SpotifyClient

client = SpotifyClient()
track = client.get_track_info("spotify_track_url")
print(f"Track: {track.get('name', 'Unknown')} by {(track.get('artists', [{}])[0].get('name', 'Unknown') if track.get('artists') else 'Unknown')}")

📊 Comprehensive Data Access¶

Extract detailed information about: - Tracks: Title, artists, album, duration, preview URLs, lyrics - Albums: Full track listings, release dates, cover art, label info - Artists: Biography, genres, popularity, follower count, top tracks - Playlists: Complete track lists, descriptions, owner information

Quick Example¶

Let's see SpotifyScraper in action with a real example:

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)

# Display the results
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"Album: {track.get('album', {}).get('name', 'Unknown')}")
print(f"Duration: {track.get('duration_ms', 0) / 1000:.0f} seconds")

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

# Don't forget to clean up!
client.close()

Output:

Track: Sweet Child O' Mine
Artist: Guns N' Roses
Album: Appetite For Destruction
Duration: 303 seconds
Preview saved to: downloads/sweet_child_o_mine.mp3

Your Journey Starts Here¶

Step 1: Installation¶

Choose your preferred installation method:

# Basic installation
pip install spotifyscraper

# With all features
pip install "spotifyscraper[all]"

# Development version
pip install git+https://github.com/AliAkhtari78/SpotifyScraper.git

📖 Read the Complete Installation Guide →

Step 2: Configuration¶

Configure SpotifyScraper for your specific needs:

# Example: Optimized for batch processing
client = SpotifyClient(
    browser_type="requests",      # Fast HTTP client
    timeout=45,                   # Reasonable timeout
    use_cache=True,              # Enable caching
    rate_limit=True,             # Respect rate limits
    log_level="INFO"             # Moderate logging
)

⚙️ Explore All Configuration Options →

Step 3: Start Building¶

With SpotifyScraper installed and configured, you're ready to: - Extract data from any Spotify URL - Download preview audio and cover art - Build music analytics applications - Create playlist management tools - And much more!

Common Use Cases¶

🎵 Music Analytics¶

# Analyze an artist's top tracks
artist = client.get_artist_info(artist_url)
print(f"Monthly Listeners: {artist['stats']['monthlyListeners']:,}")

📥 Media Downloads¶

# Download album cover in high resolution
cover_path = client.download_cover(album_url, size="large")

📋 Playlist Management¶

# Extract all tracks from a playlist
playlist = client.get_playlist_info(playlist_url)
for track in playlist['tracks']:
    print(f"- {track.get('name', 'Unknown')} by {(track.get('artists', [{}])[0].get('name', 'Unknown') if track.get('artists') else 'Unknown')}")

🔍 Batch Processing¶

# Process multiple URLs efficiently
urls = ["url1", "url2", "url3"]
results = client.get_multiple(urls, entity_type="track")

Platform Support¶

SpotifyScraper works seamlessly across all major platforms:

Best Practices¶

✅ DO¶

• Use context managers (with statements) for automatic cleanup
• Enable caching for better performance
• Respect rate limits to avoid being blocked
• Handle errors gracefully with try-except blocks
• Close the client when done

❌ DON'T¶

• Make excessive requests in short periods
• Share authentication cookies publicly
• Ignore error messages
• Use outdated versions
• Violate Spotify's Terms of Service

Troubleshooting Tips¶

🔧 Common Issues¶

1. Import Error: Make sure SpotifyScraper is installed: bash pip install --upgrade spotifyscraper

2. Connection Error: Check your internet connection and proxy settings

3. Rate Limiting: Add delays between requests: python client = SpotifyClient(request_delay=1) # 1 second delay

4. Missing Data: Some fields may be region-restricted or require authentication

What's Next?¶

Need Help?¶

We're here to support your journey:

• 💬 GitHub Discussions - Ask questions and share ideas
• 🐛 Issue Tracker - Report bugs or request features
• 📚 FAQ - Answers to frequently asked questions
• 🔧 Troubleshooting - Solutions to common problems

Ready to Start?¶

You're just a few steps away from extracting Spotify data like a pro! Begin with the Installation Guide and follow the journey through configuration to your first working script.