API Reference

REST API

Setiap tier dapat memanggil API dengan plafon lajunya sendiri. Tiap endpoint di bawah menyebut tier minimum yang membukanya. Base URL: https://bandaralert.com/api/v1

Authentication

Dua metode autentikasi tersedia. Bila keduanya dikirim, Bearer JWT dipakai lebih dulu. Gunakan salah satu:

# Opsi 1: API key (disarankan)
X-API-Key: ba_xxxxxxxxxxxxxxxxxxxxxxxx
# Opsi 2: JWT Bearer token (berlaku 30 menit)
Authorization: Bearer <JWT_TOKEN>
Kunci API diterbitkan untuk akun berbayar melalui Helpdesk. Jaga keamanan kunci API Anda dan jangan membagikannya di repositori publik.

Tier endpoint

  • Terbuka: tanpa kredensial. Tanpa kredensial, panggilan dihitung pada plafon Free.
  • Login: akun mana pun, termasuk Free.
  • Pro: Pro ke atas.
  • Quant: Quant dan API Pro.

Panggilan di atas tier Anda dijawab 403, dan badan jawabannya menyebut tier yang dibutuhkan.

Rate Limits

Satu jendela geser 1 jam, dihitung per akun, bukan per kunci API. Beberapa kunci API pada akun yang sama berbagi satu jatah. Saat batas tercapai, API menjawab 429 dengan header Retry-After berisi lama tunggu dalam detik.

TierPermintaan per jam
Free300
Pro3.000
Quant30.000
API Pro60.000
Permintaan beruntun yang rapat. Selain jendela per jam, permintaan yang datang beruntun terlalu rapat dapat ditolak sementara dengan HTTP 429. Beri jeda antarpermintaan pada panggilan berurutan dan ulangi setelah jeda singkat. Tidak ada response header X-RateLimit-Remaining; hitung sisa jatah dari jumlah permintaan Anda sendiri, dan baca Retry-After saat 429. Setiap tier berbayar dapat memanggil API; yang membedakan tier adalah KELAPANGAN, bukan izin. API Pro berada di dua kali plafon Quant. Jendelanya per AKUN, jadi menerbitkan lebih banyak kunci pada satu akun tidak menaikkannya. Bila Anda butuh lebih dari 60.000 per jam, tanyakan lewat Helpdesk sebelum membeli.

Signals

Prefix: /api/v1/signals

MetodeEndpointTierDeskripsiParameter
GET/volume-anomalyTerbukaDaftar anomali volume per saham; bawaannya hari bursa terakhirmin_severity=warning|severe&method=any&limit=50&date=YYYY-MM-DD
GET/broker-accumulationTerbukaSkor akumulasi broker (BASS) terbaru, skor tertinggi lebih dulu. Kolom identitas broker hanya untuk Pro ke atasmin_score=60&sector=&broker_tier=all&limit=50&date=YYYY-MM-DD
GET/broker-accumulation/{ticker}ProRincian akumulasi broker satu saham beserta riwayat skornyalookback_days=20
GET/smart-money-v2TerbukaSkor Smart Money seluruh saham, skor tertinggi lebih dululimit=50&min_score=0
GET/smart-money-score/{ticker}TerbukaSkor Smart Money satu saham beserta komponennyainclude_components=true
GET/ensemble/{ticker}TerbukaSkor komposit multi-sinyal satu saham beserta skor komponennya
GET/market-regimeTerbukaRezim pasar saat ini (Bull, Neutral, Bear) beserta probabilitas tiap keadaan
GET/liquidity-stressTerbukaTingkat tekanan likuiditas per saham atau per sektorlevel=warning&scope=stock&limit=50
GET/sector-rotationTerbukaRotasi sektor terhadap pembanding. Respons membawa tanggal data dan penanda kesegarannyabenchmark=IHSG&lookback_days=20

Market Data

Prefix: /api/v1/data

MetodeEndpointTierDeskripsiParameter
GET/ohlcv/{ticker}TerbukaRiwayat harga (buka, tertinggi, terendah, tutup, volume, nilai) per saham. start_date wajibstart_date=YYYY-MM-DD&end_date=YYYY-MM-DD&interval=1d|1w|1m
GET/broker-summary/{ticker}ProPembeli dan penjual teratas satu saham pada satu tanggaldate=YYYY-MM-DD&top_n=10
GET/earnings/{ticker}TerbukaKonsensus laba satu saham: tanggal laporan yang diharapkan, kejutan terbaru, proyeksi kuartalan dan tahunan
GET/earnings-calendarTerbukaSaham yang akan melaporkan laba, urut tanggaldays_ahead=30&limit=50

Stock Profile

Prefix: /api/v1/stocks

MetodeEndpointTierDeskripsiParameter
GET/{ticker}/profileTerbukaProfil singkat satu emiten: nama, sektor, fakta ringkas, anak usaha, dan status syariah

Brokers

Prefix: /api/v1/brokers

MetodeEndpointTierDeskripsiParameter
GET(hanya prefix)ProDaftar broker beserta arus bersih 5, 20, dan 60 haritier=foreign_institutional|domestic_institutional|retail_heavy|unclassified
GET/leaderboardProPeringkat broker menurut arus bersih atau jumlah saham aktifmetric=net_20d|net_5d|net_60d|active_tickers&limit=20
GET/{code}ProProfil satu broker beserta batting average
GET/{code}/holdingsProPosisi teratas broker saat ini
GET/{code}/activityProRangkaian aktivitas harian brokerdays=20

Computed

Prefix: /api/v1/computed

MetodeEndpointTierDeskripsiParameter
GET/enriched-listLoginRasio valuasi, tekanan likuiditas, dan porsi kepemilikan asing untuk seluruh saham, dalam peta per kode saham
GET/stock-enrichment/{ticker}TerbukaRingkasan lengkap satu saham: rasio kunci, kepemilikan KSEI, tekanan likuiditas, anomali volume, laba, dan ringkasan keuangan
GET/financials/{ticker}TerbukaLaba rugi, neraca, dan arus kas (periode tahunan dan kuartalan terbaru) beserta rasio kunci
GET/foreign-flow-history/{ticker}TerbukaRiwayat arus asing harian satu saham: beli, jual, dan bersihdays=30
GET/risk-reward/{ticker}TerbukaKalkulator risiko: level stop dan target, support dan resistance, serta ukuran posisi dari modal dan persen risikodays=30&portfolio_size=100000000&risk_percent=2
GET/correlationProMatriks korelasi harga penutupan beberapa saham (paling banyak 20)symbols=BBCA,BBRI&period=60
GET/broker-portfolio/{code}ProSeluruh saham yang diperdagangkan satu broker, dijumlahkan per sahamdays=30
GET/broker-leaderboardQuantNet beli dan net jual per kode broker di seluruh pasar untuk hari bursa terbarudays=1&limit=50

Broker, Insider & Corporate Data

Prefix: /api/v1/dsh

MetodeEndpointTierDeskripsiParameter
GET/broker-summary/{ticker}ProRingkasan broker harian satu saham: broker pembeli dan broker penjualas_of=YYYY-MM-DD
GET/top-brokersProPeringkat broker seluruh pasar untuk satu harias_of=YYYY-MM-DD&limit=50&order=net|total&group=FOREIGN|LOCAL|GOVERNMENT
GET/broker/{broker_code}ProDetail satu broker: profil, indikator, posisi teratas, dan aktivitasdays=20&top_holdings=30
GET/insider/recentProTransaksi orang dalam (direksi dan komisaris) terbarudays=30&action=BUY|SELL&limit=50
GET/insider/{ticker}ProTransaksi orang dalam satu emitendays=180
GET/fundamental/{ticker}ProRingkasan laporan keuangan per periode: pendapatan, laba bersih, aset, ekuitas, dan arus kaslimit=8
GET/ratios/{ticker}ProRasio utama terbaru (PER, PBV, ROE, DER, EPS, imbal dividen). Riwayat penuh dengan history=true khusus Quanthistory=false
GET/calendar/upcomingLoginKalender aksi korporasi mendatang: dividen dan jenis aksi lainnyadays=30&event_type=&ticker=
GET/calendar/todayLoginAksi korporasi hari ini

Holders

Prefix: /api/v1/holders

MetodeEndpointTierDeskripsiParameter
GET/{ticker}LoginPemegang saham 1% ke atas dari laporan KSEI terbarulimit=50
GET/{ticker}/historyLoginPerubahan kepemilikan satu emiten selama beberapa bulan terakhirmonths=12
GET/{ticker}/changesProPerubahan kepemilikan 1% ke atas dari bulan ke bulanmonths=6

Smart Money Tracker

Prefix: /api/v1/trail

MetodeEndpointTierDeskripsiParameter
GET/stock/{ticker}QuantJejak arus dana harian per saham: posisi bersih kumulatif dan broker teratasdays=20&top_brokers=10
GET/broker/{broker_code}QuantJejak arus dana harian per broker dan saham teratasnyadays=20&top_stocks=10
GET/reversalsQuantPembalikan arus dana yang besar pada satu sahamdays=10&min_flow_b=10
GET/v2/ticker/{ticker}ProInstitutional Activity Score (IAS) satu saham beserta rincian enam sinyalas_of=YYYY-MM-DD
GET/v2/ticker/{ticker}/historyProRiwayat IAS satu saham per hari bursadays=30
GET/v2/leaderboardProPeringkat saham menurut IASas_of=YYYY-MM-DD&limit=50&min_ias=60
GET/v2/reversalsProPerubahan arah sinyal IAS terbarulookback_days=5&limit=50

Network

Prefix: /api/v1/network

MetodeEndpointTierDeskripsiParameter
GET/graphQuantGraf aliran dana dari broker ke sahamdays=5&min_flow_b=1&sector=&broker_tier=&limit_stocks=30&limit_brokers=20
GET/clustersQuantKelompok broker yang memperdagangkan saham serupadays=20

Backtest

Prefix: /api/v1/backtest

MetodeEndpointTierDeskripsiParameter
GET/runQuantUji ulang historis sebuah sinyal: statistik ringkasan, kurva ekuitas, daftar transaksi, dan rincian per sahamsignal_type=bass|smart_money|volume_anomaly&threshold=70&hold_days=5|10|20&ticker=BBCA&start_date=&end_date=

Export

Prefix: /api/v1

MetodeEndpointTierDeskripsiParameter
GET/export/broker-summaryQuantRincian broker mentah satu saham sepanjang rentang tanggal, kedalaman penuh. Data sejak 21 April 2026. Ikut plafon baris harianticker=BBCA&dari=YYYY-MM-DD&sampai=YYYY-MM-DD
GET/quant-briefQuantBrief kuantitatif harian: rezim volatilitas, koridor auto rejection, dan saringan likuiditashari_likuiditas=20
GET/me/capabilitiesLoginTier akun Anda, kapabilitasnya, dan pemakaian baris harian

AI Reports

Prefix: /api/v1/ai

MetodeEndpointTierDeskripsiParameter
POST/stock-reportProLaporan AI untuk satu saham. Ada kuota harian per tierbody: {ticker, lang: id|en, timeframe: 1W|1M|3M, framework: bass_case|legacy}
POST/report-pdfProLaporan AI satu saham dalam bentuk PDF. Ada kuota harian per tierbody: {ticker, lang, timeframe, framework}
GET/daily-briefLoginRingkasan pasar harian terbaru. Free hanya cuplikan, Pro ke atas penuh
GET/brief-pdfProRingkasan pasar harian terbaru dalam bentuk PDF. Ada kuota harian per tier
POST/portfolio-riskProAnalisis risiko portofolio dari daftar posisi. Ada kuota harian per tierbody: {holdings: [{ticker, lots, avg_price}]} (1 sampai 50 posisi)
GET/quotaLoginSisa kuota AI Anda hari ini dan waktu reset

Response Format

Bentuk respons sukses TIDAK seragam di seluruh API. Tulis klien Anda mengikuti bentuk kelompok yang Anda panggil. Sebagian endpoint mengembalikan objek atau array JSON apa adanya tanpa pembungkus. Bentuk yang paling sering ditemui:

// Daftar sinyal (broker-accumulation, volume-anomaly)
{
  "data": [ ... ],
  "meta": { "total": 120, "limit": 50, "offset": 0, "date": "2026-10-08" }
}

// Harga (data/ohlcv)
{
  "ticker": "BBCA",
  "interval": "1d",
  "data": [ ... ]
}

// Analitik turunan (computed/enriched-list dan sebagian rute computed)
{
  "success": true,
  "data": { ... }
}

// Galat dari rute data
{
  "detail": {
    "error": "rate_limit_exceeded",
    "retry_after_seconds": 60
  }
}

Sebagian besar rute menaruh kode yang terbaca mesin di detail.error. Parameter yang hilang atau salah tipe dijawab 422 dengan badan berbentuk {"detail": [{"loc": [...], "msg": "...", "type": "..."}]}. Kegagalan tak terduga dijawab 500 dengan {"error": "internal_error", "message": "..."}. Tabel Error Codes di bawah memuat status HTTP-nya.

Contoh Penggunaan

import requests
from datetime import date, timedelta

API_KEY = "ba_xxxxxxxxxxxxxxxxxxxxxxxx"
BASE = "https://bandaralert.com/api/v1"
headers = {"X-API-Key": API_KEY}

# 1. Skor BASS. Kelompok ini membungkus isinya sebagai {"data": [...], "meta": {...}}
resp = requests.get(f"{BASE}/signals/broker-accumulation", headers=headers)
signals = resp.json()["data"]

for s in signals[:5]:
    # Nama medannya signal_confidence, bukan confidence.
    print(f"{s['ticker']}: BASS={s['bass_score']:.0f}, {s['signal_confidence']}")

# 2. Harga BBCA 30 hari terakhir -> {"ticker", "interval", "data": [...]}
# start_date wajib; tanpa itu server menjawab 422.
mulai = (date.today() - timedelta(days=30)).isoformat()
ohlcv = requests.get(
    f"{BASE}/data/ohlcv/BBCA",
    params={"start_date": mulai},
    headers=headers,
).json()
print(f"BBCA: {len(ohlcv['data'])} titik data")

# 3. Rezim pasar. Medan keadaannya current_state, nilainya
# foreign_inflow_bull | domestic_rotation_neutral | risk_off_bear.
# probabilities adalah objek, satu angka per keadaan, bukan satu angka tunggal.
regime = requests.get(f"{BASE}/signals/market-regime", headers=headers).json()
probs = regime["probabilities"]
print(f"Rezim: {regime['current_state']} selama {regime['days_in_state']} hari")
print(f"  bull={probs['bull']:.0%} neutral={probs['neutral']:.0%} bear={probs['bear']:.0%}")

# 4. Seluruh papan ke Excel dalam SATU permintaan. Ini lebih hemat kuota
#    daripada memanggil per saham.
import pandas as pd

rows = requests.get(
    f"{BASE}/signals/broker-accumulation",
    params={"min_score": 0, "limit": 1000},
    headers=headers, timeout=60,
).json()["data"]

pd.DataFrame(rows).to_excel("bandarmologi_eod.xlsx", index=False)

# 5. Rincian per kode broker, satu saham per permintaan (butuh tier Pro).
#    Beri jeda antarpermintaan: permintaan beruntun yang terlalu rapat dapat
#    ditolak sementara dengan HTTP 429, di luar plafon per jam akun Anda.
import time

detail = []
for r in rows:
    d = requests.get(f"{BASE}/dsh/broker-summary/{r['ticker']}",
                     headers=headers, timeout=30)
    if d.status_code == 429:
        time.sleep(int(d.headers.get("Retry-After", 5)))
        d = requests.get(f"{BASE}/dsh/broker-summary/{r['ticker']}",
                         headers=headers, timeout=30)
    if d.status_code != 200:
        continue
    detail.append(d.json())
    time.sleep(0.2)

WebSocket

Sinyal pasar tidak dikirim lewat WebSocket. Ambil sinyal tersebut lewat endpoint REST di atas.

Error Codes

HTTPKodeDeskripsi
400bad_ticker, bad_date, bad_broker_code, invalid_signal_type, invalid_hold_daysParameter tidak sah. Kode saham, tanggal, kode broker, atau pilihan gagal validasi.
401auth_required, invalid_token, invalid_api_key, token_revoked, session_revokedKredensial tidak ada, tidak sah, dicabut, atau kedaluwarsa.
403tier_upgrade_required, tier_restrictedTier Anda tidak membuka endpoint ini. Badan tier_upgrade_required memuat required_tier dan current_tier.
404not_foundSumber daya tidak ditemukan (kode saham atau kode broker).
413terlalu_banyak_baris_untuk_satu_panggilanRentang ekspor menghasilkan lebih dari 200.000 baris dalam satu panggilan. Persempit tanggalnya.
422validation errorParameter wajib hilang atau salah tipe. Badan: {detail: [{loc, msg, type}]}.
429rate_limit_exceededJendela per jam penuh. Tunggu sesuai header Retry-After. Permintaan beruntun yang terlalu rapat juga dapat ditolak sementara dengan 429.
429mcp_daily_row_budget_exceededPlafon baris harian endpoint ekspor sudah terpakai. Badan jawaban menyebut kapan hitungan direset.
500internal_errorKesalahan server tak terduga. Badan: {error, message}. Coba lagi sebentar.
502ai_generation_failedLaporan AI gagal dibuat. Coba lagi sebentar.
Tidak semua kegagalan datang sebagai status non-2xx. Beberapa endpoint di kelompok Computed memilih menurunkan mutu daripada melempar galat: kueri yang gagal mengembalikan HTTP 200 berisi {"success": false, "error": "query_failed", ...}. Klien yang hanya bercabang pada status HTTP akan membacanya sebagai hasil kosong, bukan kegagalan, jadi periksa juga field success pada endpoint tersebut.
OpenAPI Spec: Spesifikasi OpenAPI tersedia di https://bandaralert.com/openapi.json untuk tier Quant dan API Pro. Sertakan kredensial Anda pada permintaan: tanpa kredensial jawabannya 401, dan tier lain mendapat 403. Gunakan untuk membangkitkan SDK di bahasa apa pun dengan alat seperti openapi-generator. Penjelajah interaktif tidak disediakan.