A comprehensive, production-ready URL shortener with web interface, desktop GUI, analytics tracking, QR code generation, and cloud deployment support. Built with Python, Flask, and Tkinter.
- Shorten long URLs using TinyURL or Bitly
- Expand shortened URLs back to original links
- Custom short codes for branded links
- Persistent history tracking with timestamps
- Smart URL validation
- Comprehensive URL analytics
- Web Application - Flask-based responsive web interface
- Desktop GUI - Tkinter application with tabbed interface
- Analytics Dashboard - Track clicks, unique visitors, and user agents
- QR Code Generation - Auto-generate QR codes for shortened URLs
- Cloud Ready - Deploy to Render or Railway with one click
- Real-time Statistics - Hourly click patterns and visitor insights
- SQLite Database - Persistent storage for analytics data
- Python 3.8+
- Flask 2.3.2 - Web framework
- pyshorteners - URL shortening API wrapper
- SQLite3 - Analytics database
- qrcode - QR code generation
- Pillow - Image processing
- HTML5, CSS3, Bootstrap 5
- JavaScript, Chart.js for analytics
- Responsive design
- Tkinter - Native Python GUI
- Threading for non-blocking operations
- Gunicorn - WSGI HTTP Server
- Render/Railway ready configuration
- Environment variables support
Make sure you have the following installed:
- Python 3.8 or higher
- pip (Python package manager)
- Git (optional)
Clone the repository:
git clone https://github.com/stephenombuya/URL_Shorteners.py
cd url_shortenerCreate a virtual environment (recommended):
python3 -m venv venvActivate the virtual environment:
- Windows:
venv\Scripts\activate- Linux / Mac:
source venv/bin/activateInstall dependencies:
pip install -r requirements.txtRun the web server:
python app.pyOpen your browser and navigate to:
http://localhost:5000
Features available in web version:
- URL shortening with custom codes
- Analytics dashboard with charts
- QR code download
- Click tracking and visitor analytics
- History viewer
Run the GUI application:
python gui_app.pyFeatures available in GUI:
- Multi-tab interface (Shorten, Analytics, History)
- Real-time URL processing
- Copy to clipboard functionality
- Browser integration
- Visual analytics display
For command line usage:
python shortener.py- Visit
http://localhost:5000 - Enter a long URL (e.g.,
https://github.com/stephenombuya) - Choose service (TinyURL/Bitly)
- Optional: Add custom code (e.g.,
mygithub) - Click "Shorten URL"
- Copy the shortened link or download QR code
- View analytics by clicking "View Analytics"
- Launch the application
- Shorten Tab: Enter URL and get shortened link
- Analytics Tab: Enter short code to view click statistics
- History Tab: View all shortened URLs and their stats
# Shorten URL
POST /shorten
{
"long_url": "https://example.com",
"service": "tinyurl",
"custom_code": "custom"
}
# Get Analytics
GET /analytics/{short_code}
# Get Statistics
GET /api/statsThe analytics system tracks:
- Total clicks per shortened URL
- Unique visitors by IP address
- Click timestamps with hourly patterns
- User agents (browser information)
- Referrer sources
- Geographic trends (via IP analysis)
View analytics through:
- Web dashboard with Chart.js visualizations
- GUI application with formatted output
- JSON API for programmatic access
Every shortened URL automatically generates a QR code:
- Web version: Displayed instantly, can be saved
- GUI version: Generated and displayed in the result area
- Format: PNG, 200x200 pixels
- Customizable: Colors and size can be modified
To use Bitly service:
- Create an account at Bitly
- Generate your API token from developer settings
- Create a
.envfile in your project root:
BITLY_API_KEY=your_bitly_api_key_here
FLASK_ENV=production
SECRET_KEY=your_secret_key_here- Bitly will be available as an option in all interfaces
- Push your code to GitHub repository
- Create an account at Render
- Click "New +" → "Web Service"
- Connect your GitHub repository
- Render will auto-detect the configuration from
render.yaml - Add environment variables in Render dashboard
- Your app will be live at
https://your-app.onrender.com
- Install Railway CLI:
npm install -g @railway/cli - Login:
railway login - Initialize:
railway init - Deploy:
railway up - Set environment variables:
railway variables set KEY=VALUE
bash
# Install dependencies
pip install -r requirements.txt
# Run with gunicorn
gunicorn app:app --bind 0.0.0.0:8000
# Or with systemd for production
sudo systemctl start url-shortener
url_shortener/
├── app.py # Flask web application
├── gui_app.py # Tkinter GUI application
├── shortener.py # Core URL shortening logic (CLI)
├── url_shortener.py # Enhanced core with analytics
├── init_db.py # Database initialization script
├── requirements.txt # Project dependencies
├── render.yaml # Render deployment config
├── .env # Environment variables
├── history.txt # URL history log
├── analytics.db # SQLite analytics database (created by init_db.py)
├── templates/ # HTML templates for web version
│ ├── index.html # Main shortening interface
│ ├── analytics.html # Analytics dashboard
│ ├── history.html # History viewer
│ └── 404.html # Error page
├── static/ # Static files (CSS, JS, images)
└── README.md # Project documentation
The SQLite database (analytics.db) contains two tables:
url_info:
short_code(PRIMARY KEY)long_urlcreated_attotal_clicks
url_clicks:
id(PRIMARY KEY)short_urllong_urlclick_timeip_addressuser_agentreferrer
Run the test suite (if implemented):
python -m pytest tests/Manual testing checklist:
- URL shortening with valid URLs
- Error handling for invalid URLs
- Custom code functionality
- Click tracking and analytics
- QR code generation
- Database persistence
- History logging
- Web interface responsiveness
- GUI application stability
Issue: ModuleNotFoundError: No module named 'qrcode'
pip install qrcode[pil]Issue: Database locked error
# Close all connections and restart application
rm analytics.db # Backup first!
python app.py # Recreates databaseIssue: Bitly doesn't work
# Check if BITLY_API_KEY is set
echo $BITLY_API_KEY
# Or verify .env file exists and is loadedIssue: Port 5000 already in use (MacOS)
# Use a different port
python app.py --port 5001
# Or kill the process using port 5000
lsof -ti:5000 | xargs kill -9Contributions are welcome! Here's how you can help:
-
Fork the repository
-
Create a new branch
git checkout -b feature/amazing-feature
-
Make your changes
-
Commit your changes
git commit -m 'Add some amazing feature' -
Push to the branch
git push origin feature/amazing-feature
-
Open a Pull Request
- Follow PEP 8 style guide
- Add comments for complex logic
- Update documentation for new features
- Test your changes before submitting
This project is licensed under the MIT License - see the LICENSE file for details.
If you found this project useful:
- Star the repository on GitHub
- Fork it for your own use
- Report bugs via Issues
- Suggest new features
# Clone and setup
git clone https://github.com/stephenombuya/URL_Shorteners.py
cd URL_Shorteners.py
python -m venv venv
source venv/bin/activate # or venv\Scripts\activate on Windows
pip install -r requirements.txt
# Initialize the database
python init_db.py
# Select option 1 to create a new database with sample data
# Run web version
python app.py
# Run GUI version
python gui_app.py
# Run CLI version
python url_shortener.py
# Deploy to Render (after pushing to GitHub)
# Just connect your repo at https://render.com