Ripple10Hub Streams API

API yang powerful untuk mengelola data streams dari berbagai platform media sosial. Dibangun dengan Go untuk performa tinggi dan dapat menangani request secara bersamaan dengan efisien.

High Performance

Dibangun dengan Golang untuk performa maksimal dan handling request konkuren.

Secure

Dilindungi dengan API Key authentication untuk keamanan akses data Anda.

Flexible Filtering

Filter, sort, dan paginate data dengan mudah sesuai kebutuhan aplikasi Anda.

Getting Started

Quick Start

Untuk mulai menggunakan API, Anda memerlukan API Key untuk autentikasi. Setiap request ke endpoint (kecuali /health) harus menyertakan header X-API-KEY. Stream payload sekarang juga mendukung kolom topic (varchar 100) untuk menandai topik utama konten sehingga summary dan filtering bisa dilakukan berdasarkan topik.

Base URL 
http://localhost:8080

Authentication

API ini menggunakan API Key authentication. Setiap request harus menyertakan header X-API-KEY dengan API key yang valid.

Note: Untuk keamanan, jangan pernah share API key Anda di public repository atau di client-side code.

Example Request 
curl -X GET http://localhost:8080/api/streams \
  -H "X-API-KEY: your-api-key-here"

API Endpoints

GET /health

Endpoint untuk memeriksa status server. Endpoint ini tidak memerlukan autentikasi dan dapat digunakan untuk monitoring atau health check.

Example Request

cURL 
curl http://localhost:8080/health

Example Response

JSON 
{
  "status": "ok",
  "message": "Server is running"
}
POST /api/streams

Membuat data stream baru. Endpoint ini digunakan untuk menambahkan data baru dari berbagai platform media sosial seperti Twitter, Instagram, Facebook, dll.

Required Fields: channel, text, source

Request Body

JSON 
{
  "streams_id": "twitter-001",
  "source_data": "twitter_api",
  "project": 1,
  "project_name": "Brand Monitoring",
  "date": "2024-01-15T10:30:00Z",
  "channel": "twitter",
  "text": "Great product! Highly recommended!",
  "source": "https://twitter.com/user/status/123",
  "sentiment": 1,
  "user_name": "john_doe",
  "user_gender": "male"
}

Example Request

cURL 
curl -X POST http://localhost:8080/api/streams \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key-here" \
  -d '{
    "date": "2024-01-15T10:30:00Z",
    "channel": "twitter",
    "text": "Great product!",
    "source": "https://twitter.com/user/status/123",
    "sentiment": 1
  }'

Response (201 Created)

JSON 
{
  "message": "Stream created successfully",
  "data": {
    "id": 1,
    "streams_id": "twitter-001",
    "source_data": "ripple10",
    "project": 9701,
    "project_name": "Brand Monitoring",
    "date": "2024-01-15T10:30:00Z",
    "channel": "twitter",
    "text": "Great product!",
    "source": "https://twitter.com/user/status/123",
    "sentiment": 1,
    "topic": "customer_service",
    "user_name": "john_doe",
    "user_gender": "male",
    "detail_views": 100,
    "detail_likes": 10,
    "detail_shares": 2,
    "detail_comments": 5,
    "emotion_anger": 0.0,
    "emotion_joy": 0.8,
    "create_at": "2024-01-15T10:30:00Z",
    "update_at": "2024-01-15T10:30:00Z"
  }
}
GET /api/streams

Mengambil semua data stream dengan dukungan filtering, sorting, dan pagination. Semua parameter bersifat opsional.

Query Parameters

Parameter Type Description
channel string Filter berdasarkan channel (twitter, instagram, facebook, dll)
topic string Filter berdasarkan topic (misal: customer_service, promo, dsb)
is_sentiment integer Filter status enrichment sentiment (0 = belum, 1 = sudah)
is_topic integer Filter status enrichment topic (0 = belum, 1 = sudah)
is_emotion integer Filter status enrichment emotion (0 = belum, 1 = sudah)
is_ocean integer Filter status enrichment OCEAN (0 = belum, 1 = sudah)
sentiment integer Filter berdasarkan sentiment (-1: negatif, 0: netral, 1: positif)
date_from datetime Filter tanggal mulai (format: 2024-01-01 atau 2024-01-01 10:30:00)
date_to datetime Filter tanggal akhir
sort_by string Kolom untuk sorting (default: id)
sort_order string Urutan sorting: ASC atau DESC (default: ASC)
page integer Nomor halaman (default: 1)
limit integer Jumlah data per halaman (default: 10)

Example Request

cURL 
curl "http://localhost:8080/api/streams?channel=twitter&sentiment=1&sort_by=date&sort_order=DESC&page=1&limit=10" \
  -H "X-API-KEY: your-api-key-here"

Response (200 OK)

Setiap matriks menampilkan 5 entri teratas dan satu entri tambahan bernama others yang berisi total sisa data.

JSON 
{
  "message": "Streams retrieved successfully",
  "data": [
    {
      "id": 1,
      "streams_id": "twitter-001",
      "source_data": "ripple10",
      "project": 9701,
      "project_name": "Brand Monitoring",
      "date": "2024-01-15T10:30:00Z",
      "channel": "twitter",
      "text": "Sample text",
      "source": "https://twitter.com/user/status/123",
      "sentiment": 1,
      "user_name": "john_doe",
      "user_gender": "male",
      "detail_views": 100,
      "detail_likes": 10,
      "detail_shares": 2,
      "detail_comments": 5,
      "emotion_anger": 0.0,
      "emotion_joy": 0.8,
      ...
    }
  ],
  "pagination": {
    "total": 150,
    "page": 1,
    "limit": 10,
    "total_pages": 15
  }
}
GET /api/streams/:id

Mengambil detail data stream berdasarkan ID tertentu. Berguna untuk melihat informasi lengkap dari satu stream data.

Example Request

cURL 
curl http://localhost:8080/api/streams/1 \
  -H "X-API-KEY: your-api-key-here"

Response (200 OK)

Output sudah diringkas menjadi 5 entri teratas + others untuk menjaga response ringan.

JSON 
{
  "message": "Stream retrieved successfully",
  "data": {
    "id": 284,
    "streams_id": "68dc602a79c6c5913f68724b",
    "source_data": "ripple10",
    "project": 9701,
    "project_name": "Bank BRI",
    "date": "2025-09-30T21:11:48Z",
    "channel": "twitter",
    "text": "@BANKBRI_ID BRO WTF, TIBA-TIBA BANGET...",
    "source": "https://twitter.com/service_jember/status/1973133702537552090",
    "sentiment": -1,
    "topic": "customer_service",
    "user_name": "service_jember",
    "user_profile_name": "Sora",
    "user_url": "https://twitter.com/service_jember/",
    "user_followers": 171,
    "user_gender": "Male",
    "ocean_o": 0,
    "ocean_c": 0,
    "ocean_e": 0,
    "ocean_a": 0,
    "ocean_n": 0,
    "emotion_anger": 1.0,
    "emotion_sad": 0.0,
    "emotion_anticipant": null,
    "emotion_joy": 0.0,
    "emotion_fear": 0.0,
    "emotion_trust": 0.0,
    "emotion_surprise": 0.0,
    "emotion_disgusting": 0.0,
    "detail_views": 55,
    "detail_likes": 0,
    "detail_shares": 0,
    "detail_comments": 5,
    "is_sentiment": 0,
    "sentiment_date": null,
    "is_topic": 0,
    "topic_date": null,
    "is_emotion": 0,
    "emotion_date": null,
    "is_ocean": 0,
    "ocean_date": null,
    "create_at": "2025-11-21T04:28:55Z",
    "update_at": "2025-11-21T04:29:08Z"
  }
}
PUT /api/streams/:id

Memperbarui data stream yang sudah ada. Semua field dapat diupdate, timestamp update_at akan otomatis diperbarui.

Example Request

cURL 
curl -X PUT http://localhost:8080/api/streams/1 \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: your-api-key-here" \
  -d '{
    "date": "2024-01-15T10:30:00Z",
    "channel": "twitter",
    "text": "Updated text content",
    "source": "https://twitter.com/user/status/123",
    "sentiment": 0
  }'

Response (200 OK)

JSON 
{
  "message": "Stream updated successfully",
  "data": {
    "id": 1,
    "streams_id": "twitter-001",
    "channel": "twitter",
    "text": "Updated text content",
    "source": "https://twitter.com/user/status/123",
    "sentiment": 0,
    "detail_views": 100,
    "detail_likes": 10,
    "detail_shares": 2,
    "detail_comments": 5,
    ...
  }
}
PUT /api/streams/:id/topic

Endpoint khusus untuk memperbarui topic enrichment. Nilai topic_date harus menggunakan format YYYY-MM-DD HH:MM:SS.

Request Body 
{
  "topic": "Customer Service",
  "is_topic": 1,
  "topic_date": "2025-11-21 04:28:55"
}
Response 
{
  "message": "Topic updated successfully"
}
PUT /api/streams/:id/sentiment

Memperbarui sentiment akhir, flag is_sentiment, serta tanggal pemrosesan sentiment.

Request Body 
{
  "sentiment": -1,
  "is_sentiment": 1,
  "sentiment_date": "2025-11-21 04:28:55"
}
Response 
{
  "message": "Sentiment updated successfully"
}
PUT /api/streams/:id/emotion

Mengirimkan skor emosi (8 dimensi) sekaligus mengaktifkan flag is_emotion dan menyimpan tanggal pemrosesan.

Request Body 
{
  "emotion": {
    "angger": 1,
    "sad": 0.3,
    "anticipant": 0.4,
    "joy": 1,
    "fear": 0,
    "trust": 0.8,
    "surprise": 0.2,
    "disgusting": 0
  },
  "is_emotion": 1,
  "emotion_date": "2025-11-21 04:28:55"
}
Response 
{
  "message": "Emotion updated successfully"
}
PUT /api/streams/:id/ocean

Memperbarui skor kepribadian OCEAN (O, C, E, A, N) beserta flag is_ocean dan tanggal pemrosesan.

Request Body 
{
  "ocean": {
    "o": 1,
    "c": 1,
    "e": 1,
    "a": 1,
    "n": 1
  },
  "is_ocean": 1,
  "ocean_date": "2025-11-21 04:28:55"
}
Response 
{
  "message": "Ocean updated successfully"
}
DELETE /api/streams/:id

Menghapus data stream berdasarkan ID. Data yang sudah dihapus tidak dapat dikembalikan.

Warning: Operasi ini bersifat permanen dan tidak dapat dibatalkan.

Example Request

cURL 
curl -X DELETE http://localhost:8080/api/streams/1 \
  -H "X-API-KEY: your-api-key-here"

Response (200 OK)

JSON 
{
  "message": "Stream deleted successfully"
}

Summary API

Summary API menyediakan endpoint untuk mendapatkan data agregat dan breakdown dari streams table. Berguna untuk analisis, dashboard, dan reporting tanpa perlu mengambil semua data detail.

Note: Semua summary endpoints memerlukan parameter start_date dan end_date (format: YYYY-MM-DD). Field yang tidak valid akan ditampilkan sebagai null di response.

GET /api/streams/summary

Endpoint utama untuk mendapatkan semua atau sebagian summary data. Gunakan parameter include untuk memilih bagian yang ingin ditampilkan. Semua matriks breakdown akan otomatis menampilkan maksimal 5 entri teratas lalu mengelompokkan sisanya ke dalam bucket others agar response tetap ringkas.

Required Parameters

Parameter Type Description
start_date string Start date (YYYY-MM-DD), inclusive 00:00:00
end_date string End date (YYYY-MM-DD), inclusive 23:59:59

Optional Parameters

Parameter Type Description
project_id integer Filter by project ID
source_data string Filter by source_data
source string Filter by source URL
channel string Filter by channel (twitter, youtube, etc.)
topic string Filter by topic label (misal: customer_service, promo, dsb)
user string Filter by user_name
gender string Filter by user_gender
sentiment integer Filter by sentiment (-1, 0, 1)
include string Comma-separated: total,breakdown,emotions,ocean,engagement (default: all)

Example Request (All Data)

cURL 
curl -X GET "http://localhost:8080/api/streams/summary?start_date=2025-10-01&end_date=2025-10-31" \
  -H "X-API-KEY: your-api-key-here"

Example Request (Selected Parts)

cURL 
curl -X GET "http://localhost:8080/api/streams/summary?start_date=2025-10-01&end_date=2025-10-31&include=breakdown,engagement&project_id=9701" \
  -H "X-API-KEY: your-api-key-here"

Response (200 OK)

JSON 
{
  "filters": {
    "start_date": "2025-10-01",
    "end_date": "2025-10-31",
    "project_id": 9701,
    "source_data": "ripple10",
    "source": null,
    "channel": "twitter",
    "topic": null,
    "user": null,
    "gender": null,
    "sentiment": 1
  },
  "total": 1234,
  "breakdown": {
    "by_topic": [
      { "topic": "customer_service", "count": 540 },
      { "topic": "promo", "count": 420 },
      { "topic": "produk", "count": 210 },
      { "topic": "kredit", "count": 120 },
      { "topic": "partnership", "count": 80 },
      { "topic": "others", "count": 864 }
    ],
    "by_project": [
      { "project": 9701, "count": 1200 },
      { "project": 9702, "count": 34 }
    ],
    "by_source_data": [
      { "source_data": "ripple10", "count": 1234 }
    ],
    "by_channel": [
      { "channel": "twitter", "count": 1000 },
      { "channel": "youtube", "count": 234 }
    ],
    "by_user_name": [
      { "user_name": "BANKBRI_ID", "count": 57 },
      { "user_name": "solopos.espos.id", "count": 40 },
      { "user_name": "jurnalsembilan.com", "count": 32 },
      { "user_name": "urbancity.co.id", "count": 27 },
      { "user_name": "regional.espos.id", "count": 27 },
      { "user_name": "others", "count": 1292 }
    ],
    "by_sentiment": [
      { "sentiment": 1, "count": 800 },
      { "sentiment": 0, "count": 300 },
      { "sentiment": -1, "count": 134 }
    ]
  },
  "emotions": {
    "angger": 10.25,
    "sad": 5.50,
    "anticipant": 0.00,
    "joy": 12.00,
    "fear": 1.25,
    "trust": 8.00,
    "surprise": 2.75,
    "disgusting": 0.50
  },
  "ocean": {
    "o": 100,
    "c": 80,
    "e": 50,
    "a": 70,
    "n": 40
  },
  "engagement": {
    "views": 100000,
    "likes": 5000,
    "shares": 1200,
    "comments": 900
  }
}
GET /api/streams/summary/breakdown

Mengembalikan hanya breakdown (count matrices) dan total count. Berguna untuk melihat distribusi data berdasarkan berbagai dimensi.

Example Request

cURL 
curl -X GET "http://localhost:8080/api/streams/summary/breakdown?start_date=2025-10-01&end_date=2025-10-31&project_id=9701" \
  -H "X-API-KEY: your-api-key-here"

Response (200 OK)

JSON 
{
  "filters": {
    "start_date": "2025-10-01",
    "end_date": "2025-10-31",
    "project_id": 9701,
    "source_data": null,
    "source": null,
    "channel": null,
    "topic": null,
    "user": null,
    "gender": null,
    "sentiment": null
  },
  "total": 1234,
  "breakdown": {
    "by_topic": [
      { "topic": "customer_service", "count": 540 },
      { "topic": "promo", "count": 420 },
      { "topic": "produk", "count": 210 },
      { "topic": "kredit", "count": 120 },
      { "topic": "partnership", "count": 80 },
      { "topic": "others", "count": 864 }
    ],
    "by_project": [
      { "project": 9701, "count": 1200 }
    ],
    "by_source_data": [
      { "source_data": "ripple10", "count": 1234 }
    ],
    "by_source": [
      { "source": "https://twitter.com/user/status/123", "count": 10 }
    ],
    "by_channel": [
      { "channel": "twitter", "count": 1000 },
      { "channel": "youtube", "count": 234 }
    ],
    "by_user_name": [
      { "user_name": "BANKBRI_ID", "count": 57 },
      { "user_name": "solopos.espos.id", "count": 40 },
      { "user_name": "jurnalsembilan.com", "count": 32 },
      { "user_name": "urbancity.co.id", "count": 27 },
      { "user_name": "regional.espos.id", "count": 27 },
      { "user_name": "others", "count": 1292 }
    ],
    "by_user_gender": [
      { "user_gender": "male", "count": 200 },
      { "user_gender": "female", "count": 150 },
      { "user_gender": "N/A", "count": 884 }
    ],
    "by_sentiment": [
      { "sentiment": 1, "count": 800 },
      { "sentiment": 0, "count": 300 },
      { "sentiment": -1, "count": 134 }
    ]
  }
}
GET /api/streams/summary/emotions

Mengembalikan hanya agregat emosi (sum dari semua field emotion). Berguna untuk analisis sentimen dan emosi.

Example Request

cURL 
curl -X GET "http://localhost:8080/api/streams/summary/emotions?start_date=2025-10-01&end_date=2025-10-31&channel=twitter" \
  -H "X-API-KEY: your-api-key-here"

Response (200 OK)

JSON 
{
  "filters": {
    "start_date": "2025-10-01",
    "end_date": "2025-10-31",
    "project_id": null,
    "source_data": null,
    "source": null,
    "channel": "twitter",
    "user": null,
    "gender": null,
    "sentiment": null
  },
  "emotions": {
    "angger": 10.25,
    "sad": 5.50,
    "anticipant": 0.00,
    "joy": 12.00,
    "fear": 1.25,
    "trust": 8.00,
    "surprise": 2.75,
    "disgusting": 0.50
  }
}
GET /api/streams/summary/ocean

Mengembalikan hanya agregat OCEAN scores (Openness, Conscientiousness, Extraversion, Agreeableness, Neuroticism).

Example Request

cURL 
curl -X GET "http://localhost:8080/api/streams/summary/ocean?start_date=2025-10-01&end_date=2025-10-31&project_id=9701" \
  -H "X-API-KEY: your-api-key-here"

Response (200 OK)

JSON 
{
  "filters": {
    "start_date": "2025-10-01",
    "end_date": "2025-10-31",
    "project_id": 9701,
    "source_data": null,
    "source": null,
    "channel": null,
    "user": null,
    "gender": null,
    "sentiment": null
  },
  "ocean": {
    "o": 100,
    "c": 80,
    "e": 50,
    "a": 70,
    "n": 40
  }
}
GET /api/streams/summary/engagement

Mengembalikan hanya agregat engagement metrics (views, likes, shares, comments). Berguna untuk analisis performa konten.

Example Request

cURL 
curl -X GET "http://localhost:8080/api/streams/summary/engagement?start_date=2025-10-01&end_date=2025-10-31&sentiment=1" \
  -H "X-API-KEY: your-api-key-here"

Response (200 OK)

JSON 
{
  "filters": {
    "start_date": "2025-10-01",
    "end_date": "2025-10-31",
    "project_id": null,
    "source_data": null,
    "source": null,
    "channel": null,
    "user": null,
    "gender": null,
    "sentiment": 1
  },
  "engagement": {
    "views": 100000,
    "likes": 5000,
    "shares": 1200,
    "comments": 900
  }
}

Advanced Features

Filtering

API mendukung filtering berdasarkan berbagai field. Anda dapat mengkombinasikan multiple filter untuk mendapatkan data yang spesifik. Jika Anda ingin hanya mengambil data yang sudah diperkaya, gunakan flag is_sentiment, is_topic, is_emotion, atau is_ocean dengan nilai 0 atau 1.

Filter by Multiple Parameters 
curl "http://localhost:8080/api/streams?channel=twitter&sentiment=1&user_gender=male&project=1&is_topic=1" \
  -H "X-API-KEY: your-api-key-here"

Sorting

Data dapat diurutkan berdasarkan kolom apapun dengan urutan ascending (ASC) atau descending (DESC). Default sorting adalah berdasarkan ID secara ascending.

Sort by Date Descending 
curl "http://localhost:8080/api/streams?sort_by=date&sort_order=DESC" \
  -H "X-API-KEY: your-api-key-here"

Code Examples

JavaScript (Fetch API)

JavaScript 
const API_KEY = 'your-api-key-here';

// Get all streams
async function getAllStreams() {
  const response = await fetch('http://localhost:8080/api/streams', {
    headers: {
      'X-API-KEY': API_KEY
    }
  });
  const data = await response.json();
  console.log(data);
}

// Create new stream
async function createStream() {
  const response = await fetch('http://localhost:8080/api/streams', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-KEY': API_KEY
    },
    body: JSON.stringify({
      date: '2024-01-15T10:30:00Z',
      channel: 'twitter',
      text: 'Great product!',
      source: 'https://twitter.com/user/status/123',
      sentiment: 1
    })
  });
  const data = await response.json();
  console.log(data);
}

jQuery (AJAX)

jQuery 
const API_KEY = 'your-api-key-here';

// Get all streams
$.ajax({
  url: 'http://localhost:8080/api/streams',
  type: 'GET',
  headers: {
    'X-API-KEY': API_KEY
  },
  success: function(response) {
    console.log(response);
  },
  error: function(error) {
    console.error(error);
  }
});

// Create stream
$.ajax({
  url: 'http://localhost:8080/api/streams',
  type: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': API_KEY
  },
  data: JSON.stringify({
    date: '2024-01-15T10:30:00Z',
    channel: 'twitter',
    text: 'Great product!',
    source: 'https://twitter.com/user/status/123',
    sentiment: 1
  }),
  success: function(response) {
    console.log(response);
  }
});

Error Handling

API menggunakan HTTP status code standar untuk menunjukkan keberhasilan atau kegagalan request.

200 OK

Request berhasil diproses

201 Created

Data berhasil dibuat

400 Bad Request

Request tidak valid atau parameter salah

{ "error": "Invalid request body" }
401 Unauthorized

API key tidak valid atau tidak disertakan

{ "error": "Invalid API key" }
404 Not Found

Data tidak ditemukan

{ "error": "Stream not found" }
500 Internal Server Error

Terjadi kesalahan di server

{ "error": "Failed to process request" }