🚀 App Store Icon Hunter

A powerful command-line tool and REST API for searching apps and downloading their icons from App Store and Google Play Store in multiple sizes.

Perfect for developers, designers, and anyone who needs quick access to high-quality app icons for mockups, presentations, or development projects.

✨ Features

🎯 Dual Interface

• Interactive CLI with user-friendly menus and selection
• REST API Server for programmatic access and integration
• Cross-platform support (Windows, macOS, Linux)

🔍 Comprehensive Search

• App Store search using iTunes Search API
• Google Play Store search via SerpApi integration
• Multi-store search capabilities
• Country-specific search results

📱 Icon Management

• Multiple sizes: 16px to 1024px icons
• Batch downloads with progress tracking
• Custom size selection
• Organized file structure with app-specific folders

🎨 User Experience

• Interactive selection - choose specific apps to download
• Bulk download option for all search results
• Real-time progress indicators
• Detailed app information display with ratings and prices

🏗️ Project Structure

app-store-icon-hunter/
├── README.md
├── setup.py
├── requirements.txt
├── .gitignore
├── LICENSE
├── app_store_icon_hunter/          # Main package
│   ├── __init__.py
│   ├── cli/                        # Command-line interface
│   │   ├── __init__.py
│   │   └── main.py                 # Enhanced CLI with interactive selection
│   ├── api/                        # REST API server
│   │   ├── __init__.py
│   │   └── main.py                 # FastAPI server
│   ├── core/                       # Core functionality
│   │   ├── __init__.py
│   │   ├── app_store.py           # App Store API integration
│   │   ├── google_play.py         # Google Play API integration
│   │   └── downloader.py          # Icon downloading logic
│   └── utils/                      # Utility functions
│       ├── __init__.py
│       └── helpers.py             # Helper functions
├── tests/                          # Test suite
│   ├── __init__.py
│   ├── test_cli.py
│   ├── test_api.py
│   └── test_core.py
├── docs/                           # Documentation
│   ├── api.md                     # API documentation
│   ├── cli.md                     # CLI documentation
│   └── examples.md                # Usage examples
└── examples/                       # Example scripts
    ├── basic_usage.py             # Basic usage example
    ├── api-example.py             # API client example
    └── batch_download.py          # Batch download example

🚀 Quick Start

Installation

# Install from PyPI (when published)
pip install app-store-icon-hunter

# Or install from source
git clone https://github.com/Garyku0/app-store-icon-hunter.git
cd app-store-icon-hunter
pip install -e .

Environment Setup

For Google Play Store search functionality, you'll need a SerpApi key:

export SERPAPI_KEY="your_serpapi_key_here"

Basic CLI Usage

# Search and select apps interactively
icon-hunter search "Instagram"

# Search specific store
icon-hunter search "WhatsApp" --store appstore

# Auto-download all results
icon-hunter search "Spotify" --auto-download

# Custom icon sizes and output directory
icon-hunter search "Telegram" --sizes "64,128,256" --output "./my_icons"

# Interactive mode with guided prompts
icon-hunter interactive

Custom icon sizes

icon-hunter search "Discord" --sizes 64,128,256,512

Download specific app

icon-hunter download "Twitter" --sizes 128,256

### API Server Usage

```bash
# Start the API server
icon-hunter server
# or
uvicorn app_store_icon_hunter.api.main:app --reload --port 8000

# Server will be available at:
# http://localhost:8000 - API endpoints
# http://localhost:8000/docs - Interactive documentation

📖 Detailed Usage

CLI Commands

Search Command

The enhanced search command now provides interactive selection:

icon-hunter search [SEARCH_TERM] [OPTIONS]

Options:

• --store: Choose store (appstore, googleplay, both)
• --country: Country code (default: us)
• --limit: Maximum results (default: 10)
• --output: Output directory (default: icons)
• --sizes: Comma-separated icon sizes
• --auto-download/--interactive: Download mode

Interactive Mode Example:

$ icon-hunter search "Instagram"
🔍 Searching for 'Instagram' in both...

================================================================================
#   App Name                           Store           Price      Rating
================================================================================
1   Instagram                          App Store       Free       4.5/5
2   Instagram Lite                     Google Play     Free       4.2/5
3   Instagram for Business             App Store       Free       4.1/5
================================================================================

Options:
• Enter numbers separated by commas (e.g., 1,3,5)
• Enter 'all' to download all apps
• Enter 'q' to quit

Your choice: 1,2

📥 Downloading icons in sizes: 64, 128, 256, 512...
✓ Downloaded 4 icon sizes for Instagram
✓ Downloaded 4 icon sizes for Instagram Lite

✅ Successfully downloaded icons for 2 apps
📁 Icons saved to: /path/to/icons

Download Command

Direct download for specific apps:

icon-hunter download [APP_NAME] [OPTIONS]

Server Command

Start the API server:

icon-hunter server

Config Command

View current configuration:

icon-hunter config

REST API Endpoints

Search Apps

POST /search

Request Body:

{
  "term": "Instagram",
  "store": "both",
  "country": "us",
  "limit": 10
}

Response:

[
  {
    "name": "Instagram",
    "bundle_id": "com.burbn.instagram",
    "icon_url": "https://is1-ssl.mzstatic.com/image/thumb/Purple123/v4/...",
    "store": "App Store",
    "price": "Free",
    "rating": 4.5,
    "description": "Instagram is a simple way to capture and share..."
  }
]

Download Icons

POST /download

Request Body:

{
  "apps": [
    {
      "name": "Instagram",
      "icon_url": "https://...",
      "bundle_id": "com.burbn.instagram"
    }
  ],
  "sizes": [64, 128, 256, 512],
  "format": "zip"
}

Response:

{
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "started",
  "message": "Download job started for 1 apps",
  "status_url": "/status/123e4567-e89b-12d3-a456-426614174000"
}

Check Download Status

GET /status/{job_id}

Response:

{
  "job_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "completed",
  "progress": 1,
  "total": 1,
  "download_url": "/download/123e4567-e89b-12d3-a456-426614174000"
}

Download Files

GET /download/{job_id}

Returns the ZIP file with all downloaded icons.

🔧 Configuration

Environment Variables

# Google Play Store API (optional)
export SERPAPI_KEY="your_serpapi_key_here"

# Custom output directory
export ICON_HUNTER_OUTPUT_DIR="/path/to/downloads"

# API server configuration
export ICON_HUNTER_HOST="0.0.0.0"
export ICON_HUNTER_PORT="8000"

Supported Icon Sizes

The tool supports all standard icon sizes:

• Tiny: 16px, 32px
• Small: 48px, 64px
• Medium: 128px, 256px
• Large: 512px, 1024px

Platform-specific recommendations:

• iOS: 57, 72, 114, 144, 512, 1024
• Android: 48, 72, 96, 144, 192
• Web: 16, 32, 48, 96, 128
• Desktop: 128, 256, 512

🧪 Examples

Python API Client

import requests

# Search for apps
response = requests.post("http://localhost:8000/search", json={
    "term": "Instagram",
    "store": "appstore",
    "limit": 5
})
apps = response.json()

# Start download
download_response = requests.post("http://localhost:8000/download", json={
    "apps": apps[:2],  # Download first 2 apps
    "sizes": [128, 256, 512],
    "format": "zip"
})
job_id = download_response.json()["job_id"]

# Check status
status_response = requests.get(f"http://localhost:8000/status/{job_id}")
print(status_response.json())

Batch Processing Script

#!/usr/bin/env python3
import subprocess
import time

apps_to_download = [
    "Instagram", "WhatsApp", "Twitter", "Facebook", "Snapchat"
]

for app in apps_to_download:
    print(f"Downloading {app}...")
    subprocess.run([
        "icon-hunter", "download", app,
        "--sizes", "128,256,512",
        "--output", f"icons/{app.lower()}"
    ])
    time.sleep(1)  # Be respectful to APIs

print("All downloads completed!")

🏃‍♂️ Development

Setup Development Environment

# Clone the repository
git clone https://github.com/username/app-store-icon-hunter.git
cd app-store-icon-hunter

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install development dependencies
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=app_store_icon_hunter

# Run specific test file
pytest tests/test_cli.py

Code Quality

# Format code
black app_store_icon_hunter/

# Lint code
flake8 app_store_icon_hunter/

# Type checking
mypy app_store_icon_hunter/

Building and Publishing

# Build package
python setup.py sdist bdist_wheel

# Upload to PyPI (with proper credentials)
twine upload dist/*

📝 API Documentation

When running the API server, interactive documentation is available at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

How to Contribute

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

git clone https://github.com/your-username/app-store-icon-hunter.git
cd app-store-icon-hunter
pip install -e ".[dev]"

📄 License

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

🙏 Acknowledgments

• iTunes Search API for App Store data
• SerpApi for Google Play Store integration
• Click for the beautiful CLI interface
• FastAPI for the high-performance API server
• Contributors who make this project better

🐛 Bug Reports & Feature Requests

Please use GitHub Issues to report bugs or request features.

Bug Report Template:

**Description**
A clear description of the bug.

**Steps to Reproduce**
1. Run command '...'
2. See error

**Expected Behavior**
What should happen.

**Environment**
- OS: [e.g., macOS 12.0]
- Python: [e.g., 3.9.0]
- Version: [e.g., 2.0.0]

📈 Roadmap

Version 2.1.0

• Image resizing with PIL/Pillow
• SVG icon support
• Batch processing from CSV files
• Desktop GUI application

Version 2.2.0

• Icon optimization and compression
• Advanced filtering options
• Custom icon processing pipelines
• Integration with design tools (Figma, Sketch)

Version 3.0.0

• Machine learning-based icon similarity search
• Icon generation and customization
• Cloud storage integration
• Team collaboration features

📊 Performance

Benchmarks

• Search Performance: ~500ms per API call
• Download Speed: ~2MB/s average (network dependent)
• Concurrent Downloads: Up to 10 simultaneous
• Memory Usage: <50MB typical

Optimization Tips

1. Use smaller icon size sets for faster downloads
2. Leverage the --auto-download flag for batch operations
3. Set up API keys for Google Play Store access
4. Use the API server for high-frequency operations

🔐 Security

API Security

• CORS enabled for web integration
• Rate limiting on endpoints
• Input validation and sanitization
• Secure file handling

Privacy

• No user data collection
• No icon content modification
• Temporary file cleanup
• Respect for API rate limits

---

Made with ❤️ for the developer community

If this project helped you, please consider giving it a ⭐ on GitHub!