跳至主要內容

📡 Ghost Radar API

v1 對外可用端點，提供研究引用所需的一致格式。每段事實附 source_id 可逐筆回溯。

⚡ Quickstart — 5 個 endpoint × curl 範例🔑 API Keys📊 Observability
Base URL
https://ghostradar.tw/api/v1
GET/company/{ticker}
單一公司完整分析（例：2330）
GET/company/{ticker}/canonical
公開正式名稱 + 5 段來源留痕（A1 demo 入口）
GET/sources/registry
全部資料來源清單（gov_only、owner_org 篩選）
GET/compare?tickers=2330,2317,2412
多家公司並排比較（最多 5 家），每段附 source_id 可逐筆回溯
GET/ranking
排行榜，支援篩選參數
GET/etf/{code}
ETF 成分股揭露完整度（例：00878）
v1

What's new in v1（v1 更新）

  • 2026-05-10 · GET /api/v1/compare?tickers=… shipped (GR-959) — 多家公司並排比較（2-5 家），單一 HTTP 呼叫取得每家的 source-traced canonical view。
  • 2026-05-10 · GET /api/v1/sources/registry shipped (GR-953) — 全部 SRC-* 來源清單，可直接從生產環境驗證「33+ 政府來源」聲明。
  • 2026-05-10 · GET /api/v1/company/[ticker]/canonical shipped (GR-954) — per-fact source_id traceability（裁罰、碳盤查、碳費、確信、訊號 5 段，每段附來源）。
  • 2026-05-10 · 來源留痕 < 30s click-through (GR-955) — 公司頁每筆裁罰列均有 UI receipt 可直連政府原始資料。

認證與配額

  • 免費：100 calls/天/IP（無 API key）
  • 學術：5,000 calls/天（header: X-API-Key）
  • 開發者：10,000 calls/天（header: X-API-Key）
  • 商業：另議

引用格式

Ghost Radar Credibility Score (ghostradar.tw, 2026)

每個 API 回應均含：methodology_version、dataset_snapshot_id、data_asof

GET /company/{ticker}

查詢單一公司的完整可信度分析與主要留痕訊號。

參數型別預設說明
tickerstring (path)—公司代碼，如 2330
回應範例
{
  "methodology_version": "1.0",
  "dataset_snapshot_id": "2026-03-01",
  "data_asof": "2026-03-01",
  "universe_snapshot_id": null,
  "ok": true,
  "generated_at": "2026-03-01T00:00:00.000Z",
  "company": {
    "ticker": "2330",
    "company_name": "台積電",
    "market_type": "0",
    "industry": "半導體業",
    "credibility_score": 78,
    "verdict": "decent",
    "rank": 42,
    "percentile": 97.8,
    "assurance_level": "reasonable",
    "has_assurance": true,
    "top_flags": ["GF-014", "GF-003"],
    "top_signal_labels": ["確信機構與簽證同集團", "永續報告無確信"],
    "carbon_fee_liable": true,
    "cbam_exposed": false
  }
}

GET /company/{ticker}/canonical

公開讀取端點。回傳法定中文名稱與五段資料（裁罰、碳盤查、碳費、確信、訊號），每段附 source_id 可逐筆回溯。 無需 API key，CORS 開放，1 小時快取。

參數型別預設說明
tickerstring (path)—公司代碼，如 2330
fieldsstring (query)—逗號分隔，如 penalties,carbon — 只回傳指定段落
curl
# 完整 view
curl -s https://ghostradar.tw/api/v1/company/2330/canonical | jq .

# 只要 penalties + carbon 段落
curl -s 'https://ghostradar.tw/api/v1/company/2330/canonical?fields=penalties,carbon' | jq .
回應範例
{
  "ok": true,
  "disclaimer": "公開資料聚合。每段事實附 source_id，可逐筆回溯。",
  "ticker": "2330",
  "company_name_norm": "台灣積體電路製造股份有限公司",
  "as_of": "2026-03-02T00:00:00.000Z",
  "penalties": [
    {
      "source_id": "SRC-FSC-PENALTY",
      "source_name": "金管會證期局裁罰",
      "source_url": "https://...",
      "fine": 240000,
      "fine_currency": "TWD",
      "agency": "FSC",
      "date": "2025-03-15",
      "summary": "..."
    }
  ],
  "carbon_disclosure": {
    "source_id": "SRC-MOENV-GHG-REG",
    "source_name": "環境部盤查登錄",
    "deep_link": "https://ghgregistry.moenv.gov.tw/",
    "scope1": 1234, "scope2": 567, "scope3": null,
    "year": 2024, "asof": "2026-03-02T00:00:00.000Z"
  },
  "carbon_fee": {
    "obligated": true,
    "source_id": "SRC-CARBON-FEE-TARGETS",
    "source_name": "碳費徵收對象判斷欄位",
    "deep_link": "https://data.moenv.gov.tw/api/v2/ghg_p_01"
  },
  "assurance": {
    "provider": "DNV", "level": "limited", "year": 2024,
    "source_id": "SRC-TWSE-ESG-SUM",
    "source_name": "上市櫃 ESG 揭露彙總",
    "deep_link": "https://emops.twse.com.tw/server-java/t05st01_e?TYPEK=sii&co_id=2330&year={year}"
  },
  "flags": [
    { "id": "GF-R08", "label": "GF-R08", "severity": "warning", "source_id": "SRC-FSC-PENALTY" }
  ]
}

GET /ranking

取得全市場排行榜，支援多維篩選與分頁。

參數型別預設說明
limitinteger50每頁筆數，最大 200
pageinteger1頁碼（從 1 起）
sortstringscore_descscore_desc | score_asc
industrystring—依產業篩選（中文）
assurance_levelstring—none | limited | reasonable
market_typestring—listed（上市）| otc（上櫃）
gfstring—留痕訊號 ID，如 GF-014
qstring—搜尋公司名稱或代碼
回應範例
{
  "methodology_version": "1.0",
  "dataset_snapshot_id": "2026-03-01",
  "ok": true,
  "generated_at": "2026-03-01T00:00:00.000Z",
  "data": [
    {
      "ticker": "2330",
      "company_name": "台積電",
      "credibility_score": 78,
      "verdict": "decent",
      "rank": 1
    }
  ],
  "meta": {
    "total": 1957,
    "page": 1,
    "per_page": 50,
    "page_count": 40,
    "has_prev": false,
    "has_next": true,
    "methodology_version": "1.0"
  }
}

GET /etf/{code}

查詢 ESG ETF 成分股揭露完整度結果，含平均分數與保證覆蓋率。

參數型別預設說明
codestring (path)—ETF 代碼，如 00878、00850
回應範例
{
  "methodology_version": "1.0",
  "dataset_snapshot_id": "2026-03-01",
  "ok": true,
  "generated_at": "2026-03-01T00:00:00.000Z",
  "etf_code": "00878",
  "etf_name": "國泰永續高股息",
  "total": 30,
  "avg_score": 61.4,
  "min_score": 38,
  "assurance_coverage_pct": 73.3,
  "holdings": [
    {
      "weight": 0.042,
      "company": {
        "ticker": "2330",
        "credibility_score": 78,
        "verdict": "decent"
      }
    }
  ]
}

錯誤格式

所有錯誤皆返回結構化 JSON，含唯一 request_id。

{
  "error": {
    "code": "NOT_FOUND",
    "message": "ticker 9999 not found",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "methodology_version": "1.0",
  "dataset_snapshot_id": "2026-03-01"
}
codeHTTP 狀態說明
NOT_FOUND404資源不存在
BAD_REQUEST400請求參數錯誤
RATE_LIMITED429超過配額限制
UPSTREAM_FAILURE502上游資料源異常
INTERNAL500內部錯誤

快速開始

curl 範例與 company、ranking、batch 端點說明。

前往 Quickstart →
申請 API Key →查看方法論查看完整文件