README.md

metadata

title: Wildberries Analytics Dashboard
emoji: 🛍️
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 5.7.1
app_file: app.py
pinned: false
license: mit
short_description: AI-powered analytics dashboard for Wildberries marketplace
tags:
  - analytics
  - dashboard
  - e-commerce
  - wildberries
  - inventory
  - forecasting
  - business-intelligence

🛍️ Wildberries Analytics Dashboard

An AI-powered analytics dashboard for Wildberries marketplace sellers that provides sales insights and inventory forecasting capabilities.

✨ Features

• 📊 Sales Analytics: Track revenue, orders, and product performance
• 📦 Inventory Forecasting: Predict stockout dates using multiple algorithms
• ⚠️ Risk Management: Automated alerts for low stock situations
• 📈 Interactive Dashboards: Visual analytics with Plotly charts
• 🔄 Real-time Data: Integration with Wildberries API
• 🎯 Demo Mode: Works without API token for testing

🚀 Quick Start

Using with Your Wildberries API Token

1. Get your API token:

   • Go to your Wildberries seller account
   • Navigate to Settings → Access to API
   • Generate a token with Analytics and Statistics permissions

2. Configure the Space:

   • Fork this Space or duplicate it
   • Go to Settings in your Space
   • Add a new secret: WILDBERRIES_API_TOKEN with your token value

3. Start analyzing:

   • Use the Sales Analytics tab for performance insights
   • Use the Inventory Forecasting tab for stock predictions

Demo Mode

You can try the dashboard immediately without an API token - it will use sample data to demonstrate all features.

📊 Forecasting Methods

The dashboard implements multiple inventory forecasting algorithms:

1. Simple Division Method

Days Until Stockout = Current Stock ÷ Average Daily Sales

• Best for: Stable demand patterns
• Pros: Easy to understand and implement
• Cons: Doesn't account for variability

2. Safety Stock Method

Safety Stock = (Max Daily Sales × Max Lead Time) - (Avg Daily Sales × Avg Lead Time)
Adjusted Days = (Current Stock - Safety Stock) ÷ Average Daily Sales

• Best for: Critical inventory items
• Pros: Accounts for demand uncertainty
• Cons: More conservative estimates

3. Weighted Average Method

• Recent weeks: 50% weight
• Previous weeks: 30% weight
• Earlier periods: 20% weight
• Best for: Trending products
• Pros: Adapts to recent changes
• Cons: May overreact to short-term fluctuations

4. Seasonal Adjustment Method

Adjusted Demand = Base Daily Sales × Seasonal Factor
Days Until Stockout = Current Stock ÷ Adjusted Demand

• Best for: Seasonal products
• Pros: Accounts for seasonal patterns
• Cons: Requires historical seasonal data

🔧 Technical Architecture

Core Components

• Frontend: Gradio web interface with Plotly visualizations
• Backend: Python with pandas for data processing
• API Client: Custom Wildberries API integration with rate limiting
• Forecasting Engine: Multiple statistical algorithms for prediction
• Data Layer: In-memory processing with CSV export capabilities

API Integration

The dashboard respects Wildberries API rate limits:

• Maximum 300 requests per minute
• Uses token bucket algorithm
• Implements exponential backoff for 429 errors
• Automatic retry logic with circuit breaker

Deployment

Optimized for Hugging Face Spaces:

• Single-file deployment (app.py)
• Environment variable configuration
• Gradio's built-in API endpoints
• Automatic scaling and load balancing

📈 Usage Examples

Sales Analysis

# Analyze last week's performance
analyze_sales_performance("week")

# Get monthly trends
analyze_sales_performance("month")

Inventory Forecasting

# Conservative approach with safety stock
calculate_stockout_forecast("safety_stock")

# Quick estimation
calculate_stockout_forecast("simple")

# Trend-aware forecasting
calculate_stockout_forecast("weighted")

🔒 Security & Privacy

• No data storage: All processing happens in-memory
• Secure tokens: API keys stored as Hugging Face Spaces secrets
• Rate limiting: Respects API limits to prevent account issues
• Error handling: Graceful fallback to demo mode if API unavailable

🛠️ Local Development

To run locally:

# Clone the repository
git clone <your-space-url>
cd <space-name>

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export WILDBERRIES_API_TOKEN="your_token_here"

# Run the application
python app.py

📋 API Permissions Required

Your Wildberries API token needs access to:

• ✅ Analytics API
• ✅ Statistics API
• ✅ Marketplace data (for product information)

🤝 Contributing

1. Fork this Space
2. Make your changes
3. Test with demo mode
4. Submit a discussion or create your own improved version

📚 Resources

• Wildberries API Documentation
• Hugging Face Spaces Documentation
• Gradio Documentation

📄 License

MIT License - see LICENSE file for details.

🐛 Troubleshooting

Common Issues

"Demo Mode" showing instead of real data

• Check if WILDBERRIES_API_TOKEN is set in Space settings
• Verify token has correct permissions
• Ensure token hasn't expired (180-day validity)

API Rate Limit Errors

• Dashboard automatically handles rate limits
• If persistent, check if other applications are using the same token
• Consider upgrading to higher-tier API access

Empty charts or data

• May indicate no sales in selected period
• Try extending the analysis period
• Verify API token has access to your store data

🎯 Roadmap

• Multi-language support (Russian, English)
• Advanced seasonal analysis
• Export to Excel/PDF reports
• Integration with other marketplaces
• Mobile-responsive design improvements
• Real-time notifications for critical stock levels

---

Made with ❤️ for Wildberries sellers