X-EA Awards 🏆

A comprehensive platform for analyzing and ranking X (Twitter) accounts from East Africa based on various metrics including engagement, follower count, and AI-based ranking.

---

📋 Table of Contents

• Features
• Tech Stack
• Installation
• API Documentation
• Influencer Categories
• Development
• Contributing
• License

✨ Features

🔹 Backend Features

• AI-Powered Analysis

  • Advanced account ranking using machine learning
  • Multi-metric evaluation system
  • Intelligent engagement scoring

• Regional Focus

  • Specialized for East African countries
  • Location verification system
  • Country-specific insights

• Performance Metrics

  • Engagement rate tracking
  • Posting intensity analysis
  • Thread creation monitoring
  • Follower growth patterns

• Technical Features

  • Rate limit handling with progress indicators
  • Results caching for better performance
  • Data export in multiple formats (CSV/JSON)

🔸 Frontend Features

• Modern UI/UX

  • Clean, responsive design
  • Dark/Light mode support
  • Real-time updates

• Interactive Components

  • Dynamic dashboard
  • Sortable leaderboards
  • Advanced search interface
  • Data visualization with Chart.js

🛠 Tech Stack

Backend Infrastructure

Python 3.8+ │ FastAPI │ Tweepy v2 │ Pandas │ Scikit-learn

Frontend Framework

React 18 │ TypeScript │ Tailwind CSS │ HeadlessUI │ Chart.js │ Axios

🚀 Installation

Backend Setup

1. Clone and Navigate

   git clone <repository-url>
   cd Xbot

2. Install Dependencies

   pip install -r requirements.txt

3. Configure Environment

   # Create .env file in project root
   touch .env
   
   # Add your X API credentials
   API_KEY=your_api_key
   API_KEY_SECRET=your_api_key_secret
   BEARER_TOKEN=your_bearer_token
   ACCESS_TOKEN=your_access_token
   ACCESS_TOKEN_SECRET=your_access_token_secret

4. Launch Server

   python run_api.py
   # API available at http://localhost:8000

Frontend Setup

1. Navigate to Frontend

   cd frontend

2. Install Dependencies

   npm install

3. Start Development Server

   npm start
   # Frontend available at http://localhost:3000

📚 API Documentation

Core Endpoints

Endpoint	Description	Method
/	Health check	GET
/search	Account search with filters	GET
/leaderboard/{category}	Category-based rankings	GET
/dashboard/stats	Analytics & statistics	GET
/countries	Supported countries list	GET
/categories	Influencer categories	GET

Search Parameters

Parameter	Type	Description	Required
topic	string	Search keyword	Yes
country	string	Country filter	No
category	string	Influencer category	No
min_followers	integer	Minimum followers	No
min_engagement	float	Minimum engagement rate	No
sort_by	string	Sort parameter	No
page	integer	Page number	No
limit	integer	Results per page	No

👥 Influencer Categories

Nano Influencers (1K - 10K followers)

• High engagement rates
• Niche market focus
• Strong community interaction

Micro Influencers (10K - 100K followers)

• Balanced reach and engagement
• Growing authority
• Active community management

Macro Influencers (100K+ followers)

• Extensive reach
• Established authority
• Broad market influence

💻 Development

Testing

# Run backend tests
python -m pytest

# Run frontend tests
cd frontend && npm test

Production Build

# Build frontend
cd frontend && npm run build

🤝 Contributing

We welcome contributions! Here's how you can help:

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 licensed under the MIT License - see the LICENSE file for details.

---

Developed by Polymath Universata

Powered by EmerTech Labs 🚀

Made with ❤️ in Tanzania