Dokumentasi MarketShield

Pengantar

MarketShield mengubah data satelit publik menjadi langkah yang jelas bagi warga, posko dan pemerintah daerah di sekitar gunung api aktif. Semua data masuk lewat Google Earth Engine, sehingga tidak ada sensor lapangan yang perlu dipasang atau dirawat.

Status level resmi selalu mengikuti PVMBG. Prakiraan MarketShield adalah informasi pelengkap untuk persiapan, bukan pengganti perintah resmi.

Mulai cepat

1. Warga: unduh APK di /download, pilih bahasa, peran dan lokasi. Beranda langsung menyesuaikan level gunung terdekat.
2. BPBD dan posko: buka web console. Menu Ringkasan menampilkan peluang eskalasi, indikator satelit dan peringatan terbaru.
3. Developer: panggil GET https://marketshield-inception.vercel.app/api/v1/volcanoes untuk daftar gunung, lalu /volcanoes/semeru/risk untuk prakiraan.

Peran & akses

Level PVMBG

Aplikasi berubah bentuk mengikuti empat level resmi:

Jendela aksi

Jendela aksi adalah perkiraan waktu antara "satelit menunjukkan risiko naik" dan "sudah terlambat untuk bertindak dengan murah dan tenang". Nilainya diturunkan dari kurva peluang eskalasi: jumlah hari sampai peluang melewati ambang Siaga (60%).

Mesin risiko

Model gradient boosting (XGBoost) memprediksi peluang kenaikan level dalam 7 hari. Fitur dihitung per gunung setiap 6 jam:

• Perubahan backscatter radar Sentinel-1 di kawah dan alur sungai
• Jumlah titik panas FIRMS dan FRP maksimum 48 jam
• Anomali suhu permukaan MODIS terhadap baseline 90 hari
• Kolom SO₂ dan indeks aerosol Sentinel-5P, termasuk tren 3 hari
• Curah hujan GPM IMERG 24 jam di alur lahar

Label berasal dari riwayat perubahan level PVMBG. Setiap prakiraan disertai tiga faktor utama dari nilai SHAP agar petugas dapat memeriksa alasannya.

Filter sinyal

Pesan diklasifikasi menjadi HOAX, PANIC, VERIFIED, OFFICIAL atau UNVERIFIED. Aturan penting: label terverifikasi tidak pernah diberikan oleh model saja. Diperlukan sumber resmi, minimal tiga laporan yang konsisten, atau kecocokan dengan lapisan satelit. Klaim lokasi lahar dicek ke radar Sentinel-1, klaim abu dicek ke arah angin GFS dan aerosol Sentinel-5P.

Anomali harga

Untuk setiap barang darurat: deviasi = (harga pasar − HET) ÷ HET. Barang ditandai jika deviasi di atas 30% di tiga outlet atau lebih dalam 24 jam. Laporan warga memerlukan foto dan lokasi outlet.

Prioritas bantuan

Priority = Σ(pop_exposed × w_hazard) × vulnerability ÷ (aid_received + 1)

pop_exposed dihitung dari WorldPop 100 m di dalam zona KRB, sebaran abu dan aliran lahar. vulnerability menggabungkan tutupan lahan dan jarak ke posko terdekat. Setiap kiriman yang dicatat di console menurunkan skor desa tersebut sehingga bantuan berikutnya bergeser ke desa lain.

Sumber data satelit

Kesegaran & kualitas

Setiap angka di aplikasi dan console menyebut dataset dan waktu akuisisinya. Jika data lebih tua dari ambang (misalnya radar lebih dari 12 hari), tampilan diberi tanda abu-abu dan tidak dipakai untuk menaikkan peringatan.

API: ikhtisar

API REST mengembalikan JSON. URL dasar:

https://marketshield-inception.vercel.app/api/v1

Endpoint baca bersifat publik dan di-cache 5 menit. Paket Pemda dan Sektor mendapat kuota lebih besar, endpoint tulis dan webhook.

Autentikasi

Endpoint berbayar memakai kunci API di header. Kunci dibuat oleh admin instansi di console.

Authorization: Bearer ms_live_xxxxxxxxxxxxxxxx

Endpoint

Setiap respons punya kolom source: firestore untuk data langsung dari basis data, static bila basis data sedang tidak terjangkau. Endpoint risiko juga menyertakan model berisi prakiraan XGBoost terbaru bila tersedia. Isi pesan yang dicek tidak pernah disimpan.

Contoh: cek sebuah pesan berantai.

curl -X POST https://marketshield-inception.vercel.app/api/v1/signals/check \
  -H "Content-Type: application/json" \
  -d '{"text":"Katanya lahar sudah masuk Pronojiwo, sebarkan!","lang":"id"}'

{
  "label": "HOAX",
  "confidence": 0.97,
  "triggers": ["sudah masuk", "sebarkan", "katanya"],
  "satellite_check": "Radar Sentinel-1 tidak mendeteksi aliran baru ke Pronojiwo dalam 48 jam terakhir.",
  "nearest_fact": "PVMBG 08.20: Semeru tetap Level III. Tidak ada perintah evakuasi untuk wilayah ini."
}

Webhook

Daftarkan URL HTTPS untuk menerima peristiwa berikut. Setiap kiriman ditandatangani dengan header X-MS-Signature (HMAC-SHA256).

Error & batas

Catatan rilis

• v1.0.0: rilis Android pertama (arm64 & armv7), web console dengan peta 3D, API publik v1.
• v0.9: Indeks Prioritas Bantuan, pantau harga HET, siaran bertahap per kohort.
• v0.8: filter sinyal dengan cek silang Sentinel-1 dan GFS.