GSC Explorer

GSC Explorer is an open-source web application that extends Google Search Console's capabilities, providing advanced analytics, unlimited data access, AI-driven insights, and powerful visualization tools for SEO professionals and website owners.

🌟 Features

Core Capabilities

• 🔐 Google OAuth Integration - Secure sign-in with your Google Account
• 📊 Unlimited Data Access - Break free from Google Search Console's 1,000-row limitation
• 🤖 AI-Powered Insights - Leverage OpenAI for topic generation and content opportunities (Optional)
• 🔍 Brand vs Non-Brand Query Classification - Automatically categorize queries using configurable brand keywords
• 📈 Period Comparisons - Pre-calculated comparisons for:
  • Current Period vs Previous Period
  • Current Period vs Previous Year
• 📉 Interactive Visualizations - Beautiful charts and graphs powered by Plotly
• 📋 Advanced Data Tables - Filtering, sorting, and export capabilities with DataTables

Available Reports

1. Sitewide Overview - Comprehensive performance insights across different periods, countries, and devices
2. Sitewide Queries - Analyze search query performance with brand/non-brand classification
3. Sitewide Pages - Page-level performance analysis
4. Query Aggregate Report - Aggregated query performance metrics
5. Organic CTR Analysis - Click-through rate optimization insights
6. Long-Tail Opportunities - Identify high-potential long-tail queries
7. Changelog - Track application updates and features
8. Sitewide Analysis - Deep-dive analysis of site performance

Data Export

Export your data in multiple formats:

• CSV
• Excel
• PDF
• Print

🚀 Tech Stack

Backend

• Flask 3.0.0 - Web framework
• Google API Python Client - Google Search Console API integration
• Pandas 2.2.2 - Data manipulation and analysis
• Celery & Redis - Background task processing (Note: Architecture implemented but currently unused in active features)

Frontend

• DaisyUI + Tailwind CSS - Modern, responsive UI framework
• HTMX - Dynamic interactivity without complex JavaScript
• DataTables - Advanced table features (filtering, sorting, pagination, export)
• Plotly Express - Interactive charts and visualizations

AI & NLP

• OpenAI API - Content analysis and suggestions (Optional)
• NLTK & Spacy - Natural language processing for query classification

🔒 Security & Privacy

Important

Security Warning: This application handles sensitive OAuth credentials.

• Never commit your client_secrets.json or .env file to version control.
• Ensure debug mode is disabled in production.
• If self-hosting, you retain full ownership of your data; it acts as a private interface to your GSC data.

📋 Prerequisites

Before you begin, ensure you have the following installed:

• Python 3.11+
• Redis Server (Required for application startup)
• Google Cloud Project with Search Console API enabled
• OAuth 2.0 credentials (client_secrets.json)
• OpenAI API Key (Optional, for AI features)

🛠️ Installation

1. Clone the Repository

git clone https://github.com/yourusername/gsc-explorer-app.git
cd gsc-explorer-app

2. Create a Virtual Environment

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

4. Set Up Environment Variables

Create a .env file in the root directory:

SECRET_KEY=your-secret-key-here
FLASK_ENV=development
REDIS_URL=redis://localhost:6379/0
OPENAI_API_KEY=your-openai-key-optional

5. Configure Google OAuth

1. Create a project in Google Cloud Console
2. Enable the Google Search Console API
3. Create OAuth 2.0 credentials
4. Download the credentials and save as client_secrets.json in the root directory

6. Run the Application

Start Redis

Ensure your Redis server is running:

redis-server

Start the Application

python run.py

Start Celery Worker (Optional)

Currently unused, but architecture is ready for future background tasks:

celery -A app.extensions.celery worker --loglevel=info

The application will be available at https://127.0.0.1:5000 (with SSL in development mode).

Production Mode

# Using Gunicorn
gunicorn run:app --timeout 180

🐳 Deployment

The project includes configuration files for deployment:

• Procfile - Defines web process (Gunicorn) and worker (Celery)
• runtime.txt - Specifies Python version (3.11.4)

General Deployment Steps

1. Set up your hosting platform (e.g., Coolify, Railway, Render, DigitalOcean, AWS)

2. Provision Redis: Ensure your hosting provider has a Redis instance available.

3. Configure environment variables:

   • SECRET_KEY
   • FLASK_ENV=production
   • REDIS_URL - Connection string for your Redis instance
   • GOOGLE_CLIENT_ID & GOOGLE_CLIENT_SECRET (if not using file)
   • OPENAI_API_KEY (Optional)

4. Upload OAuth credentials: client_secrets.json (or use env vars).

5. Deploy:

   • The platform should detect the Procfile.
   • Ensure the web process runs.
   • (Optional) Start the celery process if you plan to enable background tasks.

Production Considerations

• Use HTTPS/SSL certificates.
• Set up proper logging.
• Security: Double-check that no secrets are committed.

📁 Project Structure

gsc-explorer-app/
├── app/
│   ├── __init__.py          # Flask app initialization
│   ├── extensions.py        # Extensions (Celery, etc.)
│   ├── routes/              # Route handlers (default, gsc, openai, etc.)
│   ├── static/              # Static files
│   └── templates/           # Jinja2 templates
├── client_secrets.json      # Google OAuth credentials
├── requirements.txt         # Python dependencies
├── Procfile                 # Process file for deployment
├── runtime.txt              # Python version specification
└── run.py                   # Application entry point

🔧 Configuration

Brand Keywords

After signing in, configure your brand keywords in the property selection page.

Session Configuration

• 300-minute lifetime
• Secure cookies (HTTPS only)
• SameSite=Lax policy

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

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

📝 License

This project is open source. Please check the repository for license details.

🐛 Known Issues

• Development mode requires SSL certificates (cert.pem and key.pem) for OAuth to work properly.

🔗 Links

• Live Demo: gscexplorer.app
• Google Search Console API: Documentation

🙏 Acknowledgments

• Google Search Console API
• Flask community
• All contributors and users of this project

📧 Support

For issues, questions, or contributions, please open an issue on the GitHub repository.

---

Made with ❤️ for the SEO community