Skip to content

Latest commit

 

History

History
228 lines (178 loc) · 5.54 KB

README.md

File metadata and controls

228 lines (178 loc) · 5.54 KB
Raw

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.

License Python FastAPI React TypeScript

Follow on X GitHub stars

📋 Table of Contents

✨ 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