🎵 Spotify Weather Mashup

A data analysis and visualization system that combines Spotify audio features with weather data to create interactive insights through a beautiful dashboard.

🌟 Features

• 🎵 Spotify Integration: Fetch audio features for tracks using Spotify Web API
• 🌤️ Weather Data: Retrieve weather information from OpenWeatherMap API
• 📊 Data Analysis: Perform correlation analysis between music and weather patterns
• 📈 Interactive Dashboard: Beautiful Plotly Dash interface with real-time filtering
• 🐳 Docker Support: Containerized deployment for easy setup
• 🧪 Comprehensive Testing: Property-based testing with Hypothesis
• 📝 Structured Logging: JSON logging with configurable levels
• ⚡ Caching: Smart caching for improved performance

🚀 Quick Start

Prerequisites

• Python 3.9+
• Docker (optional)
• Spotify Developer Account
• OpenWeatherMap API Account

1. Clone the Repository

git clone https://github.com/your-username/spotify-weather-mashup.git
cd spotify-weather-mashup

2. Set Up Environment Variables

Copy the example environment file and configure your API keys:

cp .env.example .env

Edit .env with your API credentials:

# Spotify API Configuration
SPOTIFY_CLIENT_ID=your_spotify_client_id_here
SPOTIFY_CLIENT_SECRET=your_spotify_client_secret_here

# OpenWeatherMap API Configuration
OPENWEATHER_API_KEY=your_openweather_api_key_here

# Application Configuration
DEFAULT_CITY=London
DASHBOARD_PORT=8050
DEBUG_MODE=false

3. Installation Options

Option A: Docker (Recommended)

# Build and run with Docker Compose
docker-compose up --build

# Or use the build script
./scripts/docker-build.sh
./scripts/docker-run.sh

Option B: Local Installation

# Install dependencies
pip install -r requirements.txt

# Run the application
python -m src.main

4. Access the Dashboard

Open your browser and navigate to:

• Local: http://localhost:8050
• Docker: http://localhost:8050

📖 Usage

Interactive Mode

Run the application interactively to fetch real data:

python -m src.main

You'll be prompted to enter:

• City name for weather data
• Search query for Spotify tracks

Demo Mode

Run in demo mode without API calls:

python -m src.main --demo

Docker Usage

# Start the application
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the application
docker-compose down

🏗️ Architecture

The application follows a layered architecture:

┌─────────────────────────────────────────────────────────────┐
│                    Presentation Layer                       │
│                  (Plotly Dash Dashboard)                    │
├─────────────────────────────────────────────────────────────┤
│                    Business Logic Layer                     │
│              (Data Analysis & Processing)                   │
├─────────────────────────────────────────────────────────────┤
│                    Data Access Layer                        │
│            (Spotify API & Weather API Clients)              │
├─────────────────────────────────────────────────────────────┤
│                    Infrastructure Layer                     │
│              (Configuration & Logging)                      │
└─────────────────────────────────────────────────────────────┘

Key Components

• SpotifyClient: Handles Spotify Web API authentication and data fetching
• WeatherClient: Manages OpenWeatherMap API integration
• DataProcessor: Cleans and validates data from both APIs
• DataAnalyzer: Performs statistical analysis and correlation computation
• DashboardApp: Creates interactive visualizations with Plotly Dash

📊 Dashboard Features

Visualizations

1. Correlation Heatmap: Shows relationships between audio features and weather metrics
2. Scatter Plots: Interactive plots with customizable axes
3. Time Series Charts: Trends over time for both music and weather data
4. Summary Statistics: Key metrics and statistical summaries

Interactive Features

• Real-time Filtering: Filter data by date range, city, and features
• Hover Tooltips: Detailed information on data points
• Export Functionality: Download data in JSON or CSV format
• Responsive Design: Works on desktop and mobile devices

🧪 Testing

The project includes comprehensive testing with both unit tests and property-based tests.

Run Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test types
pytest -m unit          # Unit tests only
pytest -m property      # Property-based tests only
pytest -m integration   # Integration tests only

Test Structure

tests/
├── unit/              # Unit tests
├── integration/       # Integration tests
├── property/          # Property-based tests
├── fixtures/          # Test data and fixtures
└── conftest.py        # Test configuration

🔧 Configuration

Environment Variables

Variable	Description	Default	Required
SPOTIFY_CLIENT_ID	Spotify API client ID	-	✅
SPOTIFY_CLIENT_SECRET	Spotify API client secret	-	✅
OPENWEATHER_API_KEY	OpenWeatherMap API key	-	✅
DEFAULT_CITY	Default city for weather data	London	❌
DASHBOARD_PORT	Dashboard server port	8050	❌
DASHBOARD_HOST	Dashboard server host	0.0.0.0	❌
DEBUG_MODE	Enable debug mode	false	❌
LOG_LEVEL	Logging level	INFO	❌
LOG_FORMAT	Log format (json/console)	json	❌
MAX_TRACKS	Maximum tracks to fetch	50	❌
WEATHER_DAYS	Days of weather data	7	❌
CACHE_DURATION_HOURS	Cache duration in hours	1	❌

API Setup

Spotify API

1. Go to Spotify Developer Dashboard
2. Create a new app
3. Copy the Client ID and Client Secret
4. Add them to your .env file

OpenWeatherMap API

1. Sign up at OpenWeatherMap
2. Get your free API key
3. Add it to your .env file

📈 Example Output

Correlation Analysis

Data processing completed:
- Spotify tracks: 45
- Weather records: 7
- Correlations found: 12
- Insights: 3

Key Insights:
1. Strong positive correlation between energy and temperature (r=0.67)
2. Danceability shows slight upward trend over time
3. Weather conditions significantly impact musical preferences

Dashboard Screenshots

Note: Add actual screenshots of your dashboard here

🐳 Docker Deployment

Production Deployment

# Build production image
docker build -t spotify-weather-mashup:prod .

# Run with production settings
docker run -d \
  --name spotify-weather-mashup \
  -p 80:8050 \
  --env-file .env \
  --restart unless-stopped \
  spotify-weather-mashup:prod

Docker Compose with Nginx

# Start with reverse proxy
docker-compose --profile production up -d

This includes:

• Application container
• Nginx reverse proxy
• SSL termination (configure certificates)
• Rate limiting
• Health checks

🔍 Troubleshooting

Common Issues

API Authentication Errors

# Check your API keys
python -c "
from src.config.manager import ConfigManager
config = ConfigManager().get_config()
print('Spotify ID:', config.spotify.client_id[:10] + '...')
print('Weather Key:', config.weather.api_key[:10] + '...')
"

Port Already in Use

# Find process using port 8050
lsof -i :8050

# Kill the process
kill -9 <PID>

Docker Issues

# Clean up Docker resources
docker system prune -a

# Rebuild without cache
docker-compose build --no-cache

Health Check

The application includes a health check endpoint:

# Check application health
curl http://localhost:8050/_dash-dependencies

# Or use the built-in health check
python -c "
from src.main import SpotifyWeatherMashup
app = SpotifyWeatherMashup()
print(app.health_check())
"

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Setup

# Install development dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Install pre-commit hooks
pre-commit install

# Run tests before committing
pytest

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Spotify Web API for music data
• OpenWeatherMap API for weather data
• Plotly Dash for the interactive dashboard
• Hypothesis for property-based testing

📞 Support

If you have any questions or issues:

1. Check the troubleshooting section
2. Search existing issues
3. Create a new issue

---

Made with ❤️ by Your Name# SpotifyTracksVsWeather