---
name: reference-finnhub-economic-calendar-actuals-2026-05-30
description: ForexFactory 無料 JSON は actual 値を返さない (forecast/previous のみ) → 経済指標 surprise 系機能には Finnhub /v1/calendar/economic が正解. 上流選定ルール
metadata: 
  node_type: memory
  type: reference
  originSessionId: 89aa4a63-524d-4974-9840-fd9ed17fcab8
---

2026-05-30 WIC Stage 2-α smoke test で発見した **load-bearing 知見**. 経済指標 surprise lens / 反応分析を作る場合の上流選定で再利用する.

## 結論 (1 行)

**ForexFactory `nfs.faireconomy.media/ff_calendar_thisweek.json` は `actual` field を返さない**. Finnhub `/v1/calendar/economic` は actual + estimate + prev を proper numeric で返す → こちらを使う.

## 検証手順 (再利用可能 protocol)

新しい経済指標 data source を採用する前に **必ず** 以下確認:

```bash
# 上流を直接 curl
curl -s "<UPSTREAM_URL>" | head -c 2000

# actual field 存在確認
curl -s "<UPSTREAM_URL>" | grep -oE '"actual":"[^"]+"' | head -10
# → 0 件 = 致命的 (surprise 計算不能)
# → N 件 = 採用可能

# 数値性確認 (string "0.3%" vs number 0.3)
# Finnhub: number, ForexFactory: 仮にあったとしても string
```

## 各 source の field 詳細

### ForexFactory (`nfs.faireconomy.media/ff_calendar_thisweek.json`)
- ❌ **actual: 存在しない** (key 自体が無い)
- ✅ forecast (string, "0.3%" 等)
- ✅ previous (string)
- ✅ title, country (currency code 直接), date (ISO 8601 with TZ), impact (Title-case "High"/"Medium"/"Low"/"Holiday")
- カバレッジ: 今週分のみ (~97 events), week 境界で roll-over
- 認証: 不要
- 用途: **発表前のスケジュール表示のみ** に使える. surprise/reaction lens には**使えない**

### Finnhub (`/api/v1/calendar/economic`)
- ✅ **actual: numeric (null when not released yet)**
- ✅ estimate: numeric (= forecast)
- ✅ prev: numeric (= previous)
- ✅ event (= title), country (ISO-3166 alpha-2 = US/JP/GB/EU/DE/FR/IT 等), time ("YYYY-MM-DD HH:MM:SS" treated as UTC), impact (lowercase "low/medium/high"), unit ("%" or empty)
- カバレッジ: from/to で任意 14 日 window (723 events, 71% with actual, 13 high-impact)
- 認証: key 必要 (free 60 req/min). FINNHUB_KEY は WIC で既 bind 済
- 用途: surprise / reaction lens / history accumulation 全 OK

## Currency code 変換が必要 (Finnhub の落とし穴)

Finnhub は country code (US/JP/GB/EU) を返す → currency code (USD/JPY/GBP/EUR) に変換必要. WIC では `COUNTRY_TO_CCY` map (`functions/api/economic-calendar.ts`) に 49 entries 定義. Eurozone 19 ヶ国 (DE/FR/IT/ES/NL/BE/AT/IE/PT/GR/FI/LU/SK/SI/LV/LT/EE/MT/CY/HR) は EU と同じく **EUR** に mapping. それ以外の major: SE/NO/DK/PL/TR/ZA/BR/IN/KR/RU/TH/ID/MY/PH/IL/HK/SG/TW/MX/AR/CL/CO/AE/SA. **map 未登録 country は filter out** (Africa Day 等の non-financial event 除去のため).

## Time format 注意

Finnhub の `time` field は **timezone 無し** (`"2026-05-28 12:30:00"`). 業界慣習で **UTC として扱う** のが安全. ISO 8601 化: `"2026-05-28T12:30:00Z"`.

## 数値文字列化 protocol

Finnhub は number で返すが、 `actual: 0` と `actual: null` は意味が違う (前者 = 0.0% release, 後者 = 未発表). normalize 時:
```ts
function numToStr(v: number | null | undefined, unit: string): string {
  if (v === null || v === undefined || !Number.isFinite(v)) return '';
  return Number.isInteger(v) ? `${v}${unit}` : `${v}${unit}`;
}
```

`null → ''` で **未発表** を明示. `0 → '0%'` で **0.0% release** を保持.

## 類似 source 候補 (将来の代替・補完)

| Source | actual あり? | key | cost | 備考 |
|---|---|---|---|---|
| Finnhub /calendar/economic | ✅ numeric | 要 | free 60/min | 現用 |
| ForexFactory ff_calendar_thisweek.json | ❌ | 不要 | free | actual 取れず |
| TradingEconomics | ✅ | 要 | paid (free trial 限定) | 高品質だが商用 |
| Investing.com calendar | ✅ | scrape | grey | ToS 違反リスク |
| FRED | partial | 要 | free | indicator 単位の time-series (event 単位でない) |
| Bloomberg / Refinitiv | ✅ | 要 | 高額 paid | enterprise |

## 適用範囲

- WIC `/api/economic-calendar` (現用) — 2026-05-30 切替済
- 将来の Rei 経済 lens (例: OctaTheoria `wic-events` domain 拡張案) でも同 source 推奨
- HonestConfluence_JP 等の MT4 ツールが 「経済指標 filter」 を追加する際は Finnhub 推奨

## 関連 memory

- [[project_wic_economic_indicator_stack_2026-05-30]] — 親 project
- [[reference_wic_free_market_data_apis_2026-05-25]] — 既存 free API map (この memory で extended)