Backend API Endpoints Guide
Relevant source files
The following files were used as context for generating this wiki page:
The backend API system provides real-time and batch sentiment analysis for Indonesian text, primarily focusing on YouTube comments related to Indonesian football. It is built using FastAPI for the core AI services and Next.js for frontend-facing API routes that orchestrate data fetching and analysis.
A key architectural feature is the Dual Model System, which uses a pre-trained SVM model for analyzing historical, cleaned data and a more advanced AI model (like Google Gemini, proxied through a unified scorer) for contextual analysis of raw, real-time data. This guide details the API endpoints, the underlying unified scoring system, smart filtering capabilities, and the data flow between the frontend and backend services.
System Architecture
The system is composed of two main parts: a Next.js frontend with its own API routes (/api/*) and a Python-based FastAPI backend running on http://localhost:8000. The Next.js API routes act as a bridge, fetching data from external sources (like the YouTube API) and then calling the FastAPI backend for AI-powered analysis.
Dual Model and Unified Scoring
To ensure consistency while leveraging different models, the system employs a Unified Scoring System. This system uses a shared lexicon and scoring logic but applies model-specific adjustments for different use cases.
- Static/Conservative Mode: Mimics the behavior of the original SVM model, favoring neutral classifications. Used for historical data analysis.
- Real-time/Aggressive Mode: Optimized for live analysis, boosting clear sentiment signals and reducing neutral results.
- Unified/Balanced Mode: A balanced approach for general-purpose analysis.
This architecture is visualized in the diagram below.
This diagram shows the interaction between the Next.js frontend API routes, the FastAPI backend, and external services.
Sources: README.md, UNIFIED_SCORING_SYSTEM.md, dashboard-next/app/api/live-comments/route.ts, dashboard-next/app/api/gemini-sentiment/route.ts
Unified Scoring System
The core of the sentiment analysis is the Unified Scoring System, which provides consistent results across all parts of the application. It is based on a shared lexicon, thresholds, and a robust fallback mechanism.
Consistent Lexicon
A central lexicon defines positive and negative keywords with different weights, ensuring that the same words are scored identically by all models.
| Sentiment | Strength | Keywords (Sample) | Weight |
|---|---|---|---|
| Positive | strong | sangat bagus, luar biasa, fantastic | 3.0 |
| Positive | medium | bagus, mantap, keren, hebat | 2.0 |
| Positive | weak | lumayan, cukup, ok, baik | 1.0 |
| Negative | strong | sangat jelek, terrible, kecewa sekali | 3.0 |
| Negative | medium | jelek, buruk, kecewa, kalah | 2.0 |
| Negative | weak | kurang, tidak, gak, salah | 1.0 |
Sources: config/sentiment_config_v2_optimized.py:10-41, dashboard-next/app/api/live-comments/route.ts:8-25, dashboard-next/app/api/gemini-sentiment/route.ts:40-57
Scoring Algorithm and Fallback
When the main FastAPI backend is unavailable, the Next.js API routes use a built-in fallback function that implements the same unified scoring logic.
This flowchart illustrates the decision logic for determining sentiment based on calculated scores and predefined thresholds.
Sources: dashboard-next/app/api/live-comments/route.ts:27-66, dashboard-next/app/api/gemini-sentiment/route.ts:59-118
The fallback confidence is calculated as Math.min(0.95, 0.6 + ratio * 0.3), ensuring a consistent and bounded confidence score.
Sources: dashboard-next/app/api/live-comments/route.ts:54-60, dashboard-next/app/api/gemini-sentiment/route.ts:98-104
API Endpoints
The system exposes endpoints through both the Next.js frontend and the FastAPI backend.
FastAPI Backend Endpoints (localhost:8000)
These endpoints are called by the Next.js API routes to perform sentiment analysis.
| Method | Path | Description |
|---|---|---|
POST | /predict | Analyzes a single string of text. |
POST | /predict-batch | Analyzes an array of text strings in a single request. |
Request Parameters for /predict and /predict-batch:
| Parameter | Type | Description | Required |
|---|---|---|---|
text | string | The text to analyze. (For /predict) | Yes |
texts | string[] | An array of texts to analyze. (For /predict-batch) | Yes |
model_type | string | The scoring model to use: static, realtime, or unified. Defaults to realtime. | No |
Sources: dashboard-next/app/api/gemini-sentiment/route.ts:6-21, UNIFIED_SCORING_SYSTEM.md
Next.js API Routes (localhost:3000)
These routes are consumed by the frontend UI components.
GET /api/live-comments
This endpoint fetches live YouTube comments, filters them for relevance, and performs sentiment analysis.
Request Flow:
Query Parameters:
| Parameter | Type | Description | Default |
|---|---|---|---|
videoId | string | The YouTube video ID to fetch comments from. | lDtSjKb_8Jo |
sentiment | boolean | If true, performs sentiment analysis on the comments. | false |
filter | boolean | If true (default), applies the Smart Comment Filter. Set to false to disable. | true |
maxResults | number | The maximum number of comments to fetch and process. | 200 |
Sources: dashboard-next/app/api/live-comments/route.ts:182-186
POST /api/gemini-sentiment
A proxy endpoint to the FastAPI backend's unified scorer. It can handle both single and batch predictions.
Sources: dashboard-next/app/api/gemini-sentiment/route.ts
GET /api/analytics/targets
Provides aggregated statistics on criticism targets by parsing a local CSV file. This is used for historical data visualizations.
Query Parameters:
| Parameter | Type | Description |
|---|---|---|
target | string | If provided, returns detailed stats for a specific target. Otherwise, returns aggregated data for all targets. |
The endpoint reads from data/processed/comments_fixed_labels.csv and calculates sentiment distribution for each target like PSSI, Pemain, and Pelatih.
Sources: dashboard-next/app/api/analytics/targets/route.ts
Smart Comment Filtering
A key feature of the /api/live-comments endpoint is the filterRelevantComments function, which uses a scoring system to identify comments relevant to Indonesian football.
This diagram shows how the smart filter scores comments based on positive and negative criteria to determine relevance.
Sources: dashboard-next/app/api/live-comments/route.ts:69-151
Filter Criteria:
- Positive Scoring:
- Contains football-related keywords (
timnas,pssi,pemain,sty, etc.). - Contains opinion words (
bagus,jelek,seharusnya, etc.). - Longer text length.
- Contains football-related keywords (
- Negative Scoring (Penalties):
- Contains spam keywords (
subscribe,promo,http, etc.). - Text is too short (less than 8 characters).
- Consists mostly of emojis.
- Contains excessively repeated characters.
- Contains spam keywords (
Sources: dashboard-next/app/api/live-comments/route.ts:76-141
Summary
The backend API infrastructure is a sophisticated system designed for flexible and consistent sentiment analysis. It effectively separates concerns between the Next.js frontend routes, which handle data orchestration and UI-facing logic, and the Python FastAPI backend, which focuses on core AI and ML tasks. The Unified Scoring System, Smart Comment Filtering, and robust fallback mechanisms make it a powerful and resilient tool for analyzing public opinion in real-time.