Hugging Face's logo

Spaces:
ALAMDIENG
/
waste-prediction-api
Running

App Files Community
3
waste-prediction-api / FRONTEND_API_DOC.md
ALAMDIENG's picture
ALAMDIENG
feat: implement AI autopilot, news compilation, 6-category waste composition, and API documentation
0ab1c9b
preview code
|
Raw
History Blame
13.6 kB

Aeterna AI - Front-End API Integration Guide (v4.0.0)

Dokumen ini ditujukan bagi tim Front-End untuk mengintegrasikan antarmuka pengguna dengan backend Aeterna AI (Waste Intelligence Platform).

📡 Konfigurasi Global

  • Base URL (Local): http://localhost:8001
  • Content-Type: application/json
  • CORS: Diaktifkan secara wildcard (*) untuk semua origin, method, dan header.

🗺️ Konstanta Wilayah (44 Kecamatan DKI Jakarta)

Untuk memetakan wilayah pada leaflet/map atau drop-down pilihan di FE, gunakan konstanta koordinat dan baseline berikut:

export interface RegionMetadata {
  latitude: number;
  longitude: number;
  normal_avg: number;
  warning_threshold: number;
  critical_threshold: number;
  city: 'Jakarta Pusat' | 'Jakarta Utara' | 'Jakarta Barat' | 'Jakarta Selatan' | 'Jakarta Timur' | 'Kepulauan Seribu';
}

export const KECAMATAN_DATABASE: Record<string, RegionMetadata> = {
  // JAKARTA PUSAT
  "Menteng": { latitude: -6.1950, longitude: 106.8322, normal_avg: 120.0, warning_threshold: 160.0, critical_threshold: 180.0, city: "Jakarta Pusat" },
  "Senen": { latitude: -6.1822, longitude: 106.8452, normal_avg: 180.0, warning_threshold: 220.0, critical_threshold: 240.0, city: "Jakarta Pusat" },
  "Cempaka Putih": { latitude: -6.1802, longitude: 106.8686, normal_avg: 90.0, warning_threshold: 120.0, critical_threshold: 140.0, city: "Jakarta Pusat" },
  "Johar Baru": { latitude: -6.1866, longitude: 106.8572, normal_avg: 70.0, warning_threshold: 95.0, critical_threshold: 110.0, city: "Jakarta Pusat" },
  "Kemayoran": { latitude: -6.1628, longitude: 106.8438, normal_avg: 180.0, warning_threshold: 220.0, critical_threshold: 240.0, city: "Jakarta Pusat" },
  "Sawah Besar": { latitude: -6.1554, longitude: 106.8322, normal_avg: 110.0, warning_threshold: 145.0, critical_threshold: 165.0, city: "Jakarta Pusat" },
  "Tanah Abang": { latitude: -6.2104, longitude: 106.8122, normal_avg: 250.0, warning_threshold: 320.0, critical_threshold: 350.0, city: "Jakarta Pusat" },
  "Gambir": { latitude: -6.1764, longitude: 106.8190, normal_avg: 150.0, warning_threshold: 195.0, critical_threshold: 215.0, city: "Jakarta Pusat" },

  // JAKARTA UTARA
  "Penjaringan": { latitude: -6.1264, longitude: 106.7822, normal_avg: 280.0, warning_threshold: 350.0, critical_threshold: 380.0, city: "Jakarta Utara" },
  "Tanjung Priok": { latitude: -6.1322, longitude: 106.8722, normal_avg: 260.0, warning_threshold: 320.0, critical_threshold: 350.0, city: "Jakarta Utara" },
  "Koja": { latitude: -6.1214, longitude: 106.9133, normal_avg: 190.0, warning_threshold: 240.0, critical_threshold: 270.0, city: "Jakarta Utara" },
  "Cilincing": { latitude: -6.1288, longitude: 106.9452, normal_avg: 290.0, warning_threshold: 370.0, critical_threshold: 400.0, city: "Jakarta Utara" },
  "Pademangan": { latitude: -6.1328, longitude: 106.8422, normal_avg: 140.0, warning_threshold: 180.0, critical_threshold: 200.0, city: "Jakarta Utara" },
  "Kelapa Gading": { latitude: -6.1552, longitude: 106.9022, normal_avg: 190.0, warning_threshold: 240.0, critical_threshold: 270.0, city: "Jakarta Utara" },

  // JAKARTA BARAT
  "Cengkareng": { latitude: -6.1528, longitude: 106.7322, normal_avg: 340.0, warning_threshold: 420.0, critical_threshold: 460.0, city: "Jakarta Barat" },
  "Grogol Petamburan": { latitude: -6.1622, longitude: 106.7882, normal_avg: 220.0, warning_threshold: 280.0, critical_threshold: 310.0, city: "Jakarta Barat" },
  "Kalideres": { latitude: -6.1428, longitude: 106.7022, normal_avg: 260.0, warning_threshold: 330.0, critical_threshold: 360.0, city: "Jakarta Barat" },
  "Kebon Jeruk": { latitude: -6.1922, longitude: 106.7722, normal_avg: 210.0, warning_threshold: 260.0, critical_threshold: 290.0, city: "Jakarta Barat" },
  "Kembangan": { latitude: -6.1828, longitude: 106.7382, normal_avg: 180.0, warning_threshold: 230.0, critical_threshold: 250.0, city: "Jakarta Barat" },
  "Palmerah": { latitude: -6.2028, longitude: 106.7882, normal_avg: 160.0, warning_threshold: 200.0, critical_threshold: 220.0, city: "Jakarta Barat" },
  "Taman Sari": { latitude: -6.1454, longitude: 106.8182, normal_avg: 100.0, warning_threshold: 130.0, critical_threshold: 150.0, city: "Jakarta Barat" },
  "Tambora": { latitude: -6.1500, longitude: 106.8000, normal_avg: 80.0, warning_threshold: 110.0, critical_threshold: 125.0, city: "Jakarta Barat" },

  // JAKARTA SELATAN
  "Cilandak": { latitude: -6.2928, longitude: 106.7922, normal_avg: 180.0, warning_threshold: 230.0, critical_threshold: 250.0, city: "Jakarta Selatan" },
  "Jagakarsa": { latitude: -6.3328, longitude: 106.8222, normal_avg: 220.0, warning_threshold: 280.0, critical_threshold: 310.0, city: "Jakarta Selatan" },
  "Kebayoran Baru": { latitude: -6.2422, longitude: 106.7982, normal_avg: 210.0, warning_threshold: 260.0, critical_threshold: 290.0, city: "Jakarta Selatan" },
  "Kebayoran Lama": { latitude: -6.2488, longitude: 106.7722, normal_avg: 230.0, warning_threshold: 290.0, critical_threshold: 320.0, city: "Jakarta Selatan" },
  "Mampang Prapatan": { latitude: -6.2522, longitude: 106.8182, normal_avg: 120.0, warning_threshold: 150.0, critical_threshold: 170.0, city: "Jakarta Selatan" },
  "Pancoran": { latitude: -6.2622, longitude: 106.8382, normal_avg: 130.0, warning_threshold: 160.0, critical_threshold: 180.0, city: "Jakarta Selatan" },
  "Pasar Minggu": { latitude: -6.2828, longitude: 106.8438, normal_avg: 240.0, warning_threshold: 300.0, critical_threshold: 330.0, city: "Jakarta Selatan" },
  "Pesanggrahan": { latitude: -6.2588, longitude: 106.7588, normal_avg: 160.0, warning_threshold: 200.0, critical_threshold: 220.0, city: "Jakarta Selatan" },
  "Setiabudi": { latitude: -6.2228, longitude: 106.8282, normal_avg: 190.0, warning_threshold: 240.0, critical_threshold: 270.0, city: "Jakarta Selatan" },
  "Tebet": { latitude: -6.2288, longitude: 106.8482, normal_avg: 170.0, warning_threshold: 210.0, critical_threshold: 230.0, city: "Jakarta Selatan" },

  // JAKARTA TIMUR
  "Cakung": { latitude: -6.1828, longitude: 106.9482, normal_avg: 350.0, warning_threshold: 430.0, critical_threshold: 470.0, city: "Jakarta Timur" },
  "Cipayung": { latitude: -6.3128, longitude: 106.9022, normal_avg: 140.0, warning_threshold: 180.0, critical_threshold: 200.0, city: "Jakarta Timur" },
  "Ciracas": { latitude: -6.3228, longitude: 106.8782, normal_avg: 190.0, warning_threshold: 240.0, critical_threshold: 270.0, city: "Jakarta Timur" },
  "Duren Sawit": { latitude: -6.2228, longitude: 106.9282, normal_avg: 300.0, warning_threshold: 370.0, critical_threshold: 410.0, city: "Jakarta Timur" },
  "Jatinegara": { latitude: -6.2222, longitude: 106.8682, normal_avg: 240.0, warning_threshold: 300.0, critical_threshold: 330.0, city: "Jakarta Timur" },
  "Kramat Jati": { latitude: -6.2722, longitude: 106.8682, normal_avg: 220.0, warning_threshold: 270.0, critical_threshold: 300.0, city: "Jakarta Timur" },
  "Makasar": { latitude: -6.2622, longitude: 106.8782, normal_avg: 160.0, warning_threshold: 200.0, critical_threshold: 220.0, city: "Jakarta Timur" },
  "Matraman": { latitude: -6.2022, longitude: 106.8582, normal_avg: 130.0, warning_threshold: 160.0, critical_threshold: 180.0, city: "Jakarta Timur" },
  "Pasar Rebo": { latitude: -6.3122, longitude: 106.8522, normal_avg: 150.0, warning_threshold: 190.0, critical_threshold: 210.0, city: "Jakarta Timur" },
  "Pulo Gadung": { latitude: -6.1922, longitude: 106.8922, normal_avg: 220.0, warning_threshold: 270.0, critical_threshold: 300.0, city: "Jakarta Timur" },

  // KEPULAUAN SERIBU
  "Kepulauan Seribu Utara": { latitude: -5.5722, longitude: 106.5522, normal_avg: 11.0, warning_threshold: 15.0, critical_threshold: 18.0, city: "Kepulauan Seribu" },
  "Kepulauan Seribu Selatan": { latitude: -5.7722, longitude: 106.6522, normal_avg: 9.0, warning_threshold: 12.0, critical_threshold: 15.0, city: "Kepulauan Seribu" }
};

🔌 Referensi API Endpoint

1. Mengambil Berita Ter-crawled Harian

Endpoint ini menyajikan database berita seputar persampahan DKI Jakarta yang diperbarui berkala setiap 1 jam.

  • URL: /api/v1/news
  • Method: GET
  • Headers: Accept: application/json
  • Response Schema (200 OK):
    [
  {
    "title": "DKI Uji Coba Penarikan Retribusi Sampah Pelayanan Kebersihan Harian",
    "source": "Antara News",
    "url": "https://www.antaranews.com/tag/sampah-jakarta",
    "date_fetched": "2026-07-10",
    "summary": "Pemprov DKI Jakarta merencanakan uji coba penarikan retribusi pelayanan kebersihan/sampah berdasarkan golongan daya listrik..."
  }
]

2. Prediksi AI Otonom (Autopilot Mode)

Mengambil prediksi otonom untuk ke-44 kecamatan sekaligus untuk hari ini. Berguna untuk dashboard autopilot utama.

  • URL: /api/v1/autopilot
  • Method: GET
  • Response Schema (200 OK):
    {
  "status": "success",
  "date": "2026-07-10",
  "total_volume_ton": 8105.42,
  "total_trucks": 1640,
  "top_kecamatan": [
    {
      "location": "Cakung",
      "volume_ton": 355.20,
      "trucks": 72,
      "status": "SAFE",
      "city": "Jakarta Timur"
    }
  ],
  "rainy_regions": 0,
  "event_today": null
}

3. Simulasi Prediksi Wilayah (Predictor Tool)

Melakukan peramalan timbulan sampah untuk kecamatan tertentu dengan parameter simulasi cuaca/event keramaian.

  • URL: /api/v1/predict
  • Method: POST
  • Request Body:
    interface PredictionRequest {
  forecast_days: number;       // Ambang batas: 1 - 30 hari
  rainfall_mm: number;         // Curah hujan override (0.0 = Auto Open-Meteo)
  event_scale: number;         // 0 (none) sampai 5 (massive crowd)
  location: string;            // Salah satu nama dari 44 kecamatan
  granularity: 'daily' | 'hourly';
  model_type: 'chronos' | 'gradient_boosting';
}
  • Contoh Request Payload:
    {
  "forecast_days": 7,
  "rainfall_mm": 0.0,
  "event_scale": 0,
  "location": "Menteng",
  "granularity": "daily",
  "model_type": "gradient_boosting"
}
  • Response Schema (200 OK):
    {
  "status": "success",
  "message": "Normal conditions.",
  "confidence_score": 0.9828,
  "data": {
    "prediction_results": [
      {
        "date": "2026-07-10",
        "location": "Menteng",
        "total_volume_ton": 120.54,
        "organic_waste_ton": 60.11,
        "plastic_waste_ton": 27.66,
        "paper_waste_ton": 13.86,
        "glass_waste_ton": 3.86,
        "metal_waste_ton": 2.53,
        "textile_waste_ton": 5.06,
        "other_waste_ton": 7.46,
        "recommended_trucks": 25,
        "risk_status": "SAFE",
        "event_info": null,
        "hourly_breakdown": null
      }
    ],
    "logistics_plan": {
      "trucks_needed": 25,
      "manpower": 75,
      "estimated_duration_hours": 24.1,
      "efficiency_rate": "85% (Optimal)"
    }
  }
}

4. Unduh Berkas CSV Prediksi

Mengunduh berkas tabel data hasil simulasi prediksi.

  • URL: /api/v1/predict/csv
  • Method: POST
  • Request Body: Sama dengan request /api/v1/predict
  • Response: Binary Blob (text/csv stream file).

5. Mengambil Peringatan Operasional Dinamis (Alerts)

Mendapatkan peringatan kritis wilayah yang volumenya melebihi ambang batas warning/critical.

  • URL: /api/v1/alerts
  • Method: GET
  • Query Parameters: location (opsional, untuk menyaring satu kecamatan)
  • Response Schema (200 OK):
    {
  "status": "success",
  "alert_count": 2,
  "alerts": [
    {
      "date": "2026-07-10",
      "location": "Cakung",
      "status": "WARNING",
      "estimated_volume_ton": 435.0,
      "message": "Alert: WARNING volume expected at Cakung"
    }
  ],
  "last_updated": "2026-07-10T20:52:00.123456"
}

⚡ Contoh Integrasi Frontend (Axios / JavaScript)

Berikut adalah contoh cara menarik data prediksi Autopilot dan memuatnya ke komponen halaman FE Anda:

import axios from 'axios';

const BACKEND_URL = 'http://localhost:8001';

// 1. Memuat Umpan Berita AI
export async function getWasteNews() {
  try {
    const res = await axios.get(`${BACKEND_URL}/api/v1/news`);
    return res.data; // Mengembalikan array berita
  } catch (error) {
    console.error("Gagal menarik berita sampah:", error);
    return [];
  }
}

// 2. Memuat Data Autopilot Otonom DKI
export async function getAutopilotData() {
  try {
    const res = await axios.get(`${BACKEND_URL}/api/v1/autopilot`);
    return res.data;
  } catch (error) {
    console.error("Gagal memuat autopilot data:", error);
    return null;
  }
}

// 3. Menjalankan Prediksi Manual (Simulation)
export async function postSimulationPrediction(kecamatan, hari = 7, model = 'gradient_boosting') {
  const payload = {
    forecast_days: hari,
    rainfall_mm: 0.0, // Auto
    event_scale: 0,
    location: kecamatan,
    granularity: hari <= 7 ? 'hourly' : 'daily',
    model_type: model
  };

  try {
    const res = await axios.post(`${BACKEND_URL}/api/v1/predict`, payload);
    return res.data;
  } catch (error) {
    console.error("Gagal melakukan prediksi simulasi:", error);
    throw error;
  }
}