locate-the-news / README.md
README.md
Raw

Locate the News 🌍

AI-Powered Spatial Journalism Platform

Status Tech License

Locate the News is a global news mapping application that transforms traditional news consumption into a spatial experience. By integrating Natural Language Processing (NLP) and Mapbox GL JS, it visualizes real-time global events, extracts precise locations from text, and analyzes sentiment to highlight crisis zones.

πŸ“Έ Screenshots

Global Sentiment Overview

Global Overview

Smart Clustering & HUD

Popup List

Crisis Detection (Red Alert)

Crisis View

Detailed News Reading

Article Detail

The interface features a custom "Glassmorphism" design with 3D interactions.

🌍 Features

  • πŸ—ΊοΈ Interactive Global Map: High-performance 3D visualization using Mapbox GL JS.
  • πŸ” NLP-Powered Extraction: Automatic location and entity (GPE) extraction from news articles using spaCy.
  • πŸ“Š Sentiment Analysis: Real-time sentiment scoring (Crisis πŸ”΄, Neutral πŸ”΅, Positive 🟒) using TextBlob & VADER.
  • 🧩 Multi-Source Integration: Aggregates data from NewsAPI and RSS feeds (BBC, Euronews, TRT World).
  • πŸ“ Intelligent Clustering: Uses Supercluster for efficient multi-level zoom visualization.
  • ⚑ Smart Caching: Implements TTL-based caching to optimize API usage.

πŸ› οΈ Technologies

Backend (The Intelligence)

  • Framework: FastAPI (Python)
  • NLP & AI: spaCy (en_core_web_sm), TextBlob
  • Data Parsing: Feedparser (RSS), Requests
  • Geocoding: Geopy & Custom Caching logic
  • Database: SQLAlchemy with SQLite

Frontend (The Visualization)

  • Framework: React.js
  • Mapping: Mapbox GL JS, react-map-gl
  • Styling: Modern CSS with Glassmorphism effects
  • Animations: Framer Motion

πŸš€ Getting Started

Prerequisites

Quick Start

  1. Backend Setup:

    cd backend
python -m venv venv
# Windows: venv\Scripts\activate | Mac/Linux: source venv/bin/activate

pip install -r requirements.txt
python -m spacy download en_core_web_sm  # Crucial: Downloads the NLP model

# Create a .env file and add: NEWS_API_KEY=your_key
python -m app.main

  2. Frontend Setup:

    cd frontend
npm install

# Create a .env file and add: REACT_APP_MAPBOX_TOKEN=your_token
npm start

πŸ“‚ Project Structure

LocateTheNews/
β”œβ”€β”€ backend/            # FastAPI backend
β”‚   β”œβ”€β”€ app/
β”‚   β”‚   β”œβ”€β”€ main.py     # Application entry point
β”‚   β”‚   β”œβ”€β”€ models.py   # Database models
β”‚   β”‚   β”œβ”€β”€ database.py # DB Connection & Session
β”‚   β”‚   β”œβ”€β”€ routers/    # API endpoints (events)
β”‚   β”‚   └── services/   # NLP, Sentiment & News Fetching
β”‚   └── requirements.txt
β”œβ”€β”€ frontend/           # React frontend
β”‚   β”œβ”€β”€ src/
β”‚   β”‚   β”œβ”€β”€ components/ # Map, HUD, and Article UI components
β”‚   β”‚   β”œβ”€β”€ api/        # Axios client & API endpoints
β”‚   β”‚   β”œβ”€β”€ styles/     # CSS modules for Glassmorphism
β”‚   β”‚   └── App.js      # Main Application logic
β”‚   └── package.json
β”œβ”€β”€ screenshots/        # Project visual assets
β”œβ”€β”€ docs/               # Technical documentation
β”œβ”€β”€ data/               # Local data storage (SQLite DB)
β”œβ”€β”€ docker-compose.yml  # Docker orchestration (optional)
└── README.md

πŸ“œ Context & Credits

This project was developed as a graduation/capstone project for the Computer Engineering Department at Muğla Sıtkı Koçman University.

Developer: Ceyda ArΔ±k

Advisor: Doç. Dr. Barış Ethem Süzek

Powered by GitFront