# Locate the News 🌍
### AI-Powered Spatial Journalism Platform

![Status](https://img.shields.io/badge/Status-Prototype-blue)
![Tech](https://img.shields.io/badge/Stack-FastAPI_React_Mapbox-orange)
![License](https://img.shields.io/badge/License-MIT-green)

**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

<table>
  <tr>
    <td width="50%">
      <h3 align="center">Global Sentiment Overview</h3>
      <div align="center">
        <img src="screenshots/global-overview.jpg" width="100%" alt="Global Overview">
      </div>
    </td>
    <td width="50%">
      <h3 align="center">Smart Clustering & HUD</h3>
      <div align="center">
        <img src="screenshots/popup-list.jpg" width="100%" alt="Popup List">
      </div>
    </td>
  </tr>
  <tr>
    <td width="50%">
      <h3 align="center">Crisis Detection (Red Alert)</h3>
      <div align="center">
        <img src="screenshots/crisis-view.jpg" width="100%" alt="Crisis View">
      </div>
    </td>
    <td width="50%">
      <h3 align="center">Detailed News Reading</h3>
      <div align="center">
        <img src="screenshots/article-detail.jpg" width="100%" alt="Article Detail">
      </div>
    </td>
  </tr>
</table>

> *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
- Python 3.8+
- Node.js 14+
- A valid [NewsAPI](https://newsapi.org) Key and [Mapbox](https://mapbox.com) Token.

### Quick Start

1. **Backend Setup**:
   ```bash
   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**:
   ```bash
   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