yirugi
/
stock-oracle
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
You cannot select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
main
Branches Tags
${ item.name }
Create tag ${ searchTerm }
Create branch ${ searchTerm }
from 'fd4816dbbd'
${ noResults }
stock-oracle/docs/DATA_COVERAGE.md

9.5 KiB
Raw Blame History Unescape Escape

Data Coverage & Backfill Guide

각 API 엔드포인트의 실제 DB 보유 데이터 범위와 과거 데이터 백필 방법을 정리한 문서입니다.

마지막 업데이트: 2026-03-23 DB 실측 기준

요약 테이블

엔드포인트 데이터 소스 DB 저장 현재 보유 범위 이론적 최대 범위 백필 필요
/price Yahoo Finance ✅ 2018-04-24 ~ 현재 (1682 티커) 20년+ 요청 기반 자동 누적
/alpaca/bars, /alpaca/data Alpaca API ✅ 테스트 데이터만 ~20년 필요시 수동
/finra/short-volume FINRA CDN ✅ 2026-02-10 ~ 현재 (28거래일) 수년치 ⚠️ 백필 권장
/etf/holdings SEC EDGAR (NPORT) ✅ (스냅샷) 요청 기반 자동 누적 2019년~ 요청 기반 자동 누적
/filings/search SEC EDGAR ✅ 1994-01-05 ~ 현재 (1598 티커) 1994년~ 요청 기반 자동 누적
/stocks/most-active Yahoo 실시간 스크래핑 ❌ 실시간만 없음 해당 없음
/stocks/52-week-gainers Yahoo 실시간 스크래핑 ❌ 실시간만 없음 해당 없음
/stocks/trending Yahoo 실시간 스크래핑 ❌ 실시간만 없음 해당 없음
/overlay/{symbol} Yahoo/YouTube/Wikipedia/FINRA ✅ 2026-03-17 ~ 현재 (50 심볼) 서비스 시작 이후 과거 백필 불가
/overlay/{symbol}/headlines Yahoo Finance RSS ✅ 2026-02-24 ~ 현재 서비스 시작 이후 과거 백필 불가
/overlay/{symbol}/wiki Wikipedia Pageviews API ✅ 2015-12-26 ~ 현재 2015년~ 자동 수집됨

엔드포인트별 상세

/api/v1/price — 주가 (Yahoo Finance)

현재 DB 보유: 2018-04-24 ~ 현재, 1682 티커, 약 190만 행

조회 파라미터:

  • period: 1d 7d 30d 1m 3m 6m 1y 2y 5y max
  • start_date + end_date: 특정 날짜 범위 (YYYY-MM-DD)
  • quarters: ["2024Q1", "2024Q2"] 형식

동작 방식: DB 캐시 우선 → 누락 구간만 Yahoo Finance에서 실시간 페치 → 자동 저장

백필: 별도 작업 불필요. 처음 조회 시 자동으로 인제스트됨.

# 특정 티커 과거 데이터 미리 채우기 (선택 사항)
curl -X POST "http://localhost:18001/api/v1/price/data" \
  -H "Content-Type: application/json" \
  -d '{"ticker": "AAPL", "start_date": "2020-01-01", "end_date": "2024-12-31"}'

/api/v1/alpaca — 주가 (Alpaca API)

현재 DB 보유: 테스트 데이터만 (AAPL 27일치). 실 운용 데이터 없음.

조회 파라미터:

  • start_date + end_date 필수
  • interval: 1m 5m 15m 1h 1d 1w 1mo

필수 조건: ALPACA_API_KEY, ALPACA_SECRET_KEY 환경 변수 설정 필요.

백필: /alpaca/data/{ticker} 엔드포인트 호출 시 자동으로 DB에 저장됨.

# Alpaca 과거 데이터 수동 백필
curl "http://localhost:18001/api/v1/alpaca/data/AAPL?start_date=2020-01-01&end_date=2024-12-31&interval=1d"

⚠️ /alpaca/bars는 DB에 저장되지 않음 (raw 조회 전용). DB 저장은 /alpaca/data만 해당.

/api/v1/finra — FINRA 공매도 (RegSHO)

현재 DB 보유: 2026-02-10 ~ 2026-03-20, 28거래일 (서비스 가동 시점부터)

데이터 소스인 FINRA CDN은 수년치 과거 파일을 보유하고 있으나, 현재 DB에는 최근 28일치만 있음.

조회 파라미터:

  • days: 최근 N일 (기본 30, 최대 365)
  • limit: 반환 최대 건수 (기본 100, 최대 1000)

⚠️ 백필 방법:

# 단일 날짜 백필
POST /api/v1/finra/admin/ingest?date=2025-01-02&force=false

# 날짜 범위 백필 (권장)
POST /api/v1/finra/admin/ingest?start_date=2024-01-01&end_date=2026-02-09&force=false

curl 예시:

# 2024년 전체 백필 (~252 거래일 × ~11,000 심볼 = ~280만 행)
curl -X POST "http://localhost:18001/api/v1/finra/admin/ingest?start_date=2024-01-01&end_date=2024-12-31"

# 2025년 전체 백필
curl -X POST "http://localhost:18001/api/v1/finra/admin/ingest?start_date=2025-01-01&end_date=2025-12-31"

# 운영 공백 구간 채우기 (2026-01-01 ~ 2026-02-09)
curl -X POST "http://localhost:18001/api/v1/finra/admin/ingest?start_date=2026-01-01&end_date=2026-02-09"

주의: 1년치 백필 시 ~3000 HTTP 요청 + DB write. 수십 분 소요될 수 있음. FINRA CDN은 API 키 없이 사용 가능하나 과부하를 피하기 위해 범위를 분할해서 실행 권장.

/api/v1/etf — ETF 보유 종목 (SEC EDGAR)

현재 DB 보유: 요청된 ETF 스냅샷만 (요청 기반 자동 누적)

이론적 범위: 2019년~ (NPORT-P 도입 이후). 일부 ETF는 더 이전 N-Q 파일링 존재.

조회 파라미터:

  • as_of_date: 기준 날짜 (YYYY-MM-DD). 가장 가까운 파일링 자동 선택.
  • 생략 시: 가장 최신 파일링 반환.

동작 방식: 첫 조회 시 SEC EDGAR에서 자동 페치 → 스냅샷 DB 저장. 재조회 시 캐시.

# 특정 날짜 기준 ETF 보유 종목 조회 (자동 캐시)
curl "http://localhost:18001/api/v1/etf/holdings/QQQ?as_of_date=2023-12-31"
curl "http://localhost:18001/api/v1/etf/holdings/SPY?as_of_date=2022-06-30"

ETF 출시 이전 날짜 요청 시 availability 필드에 가능한 날짜 범위 반환됨.

/api/v1/filings — SEC 공시 (EDGAR)

현재 DB 보유: 1994-01-05 ~ 현재, 1598 티커, 약 8000일치

지원 양식: 8-K, 6-K, 20-F, 40-F

조회 파라미터:

  • form_type: 쉼표 구분 (예: 8-K,6-K)
  • start_date + end_date: 공시 날짜 범위
  • limit / offset: 페이지네이션 (최대 100)

동작 방식: 첫 조회 시 SEC EDGAR 자동 인덱싱 → DB 저장. 이후 DB 캐시. 1시간 Redis 캐시.

백필: 별도 작업 불필요. GET /filings/search/{ticker} 최초 호출 시 자동 인덱싱됨.

# 특정 티커 전체 8-K 조회 (자동 인덱싱)
curl "http://localhost:18001/api/v1/filings/search/AAPL?form_type=8-K&start_date=2020-01-01"

# 여러 티커 일괄 인덱싱
curl -X POST "http://localhost:18001/api/v1/filings/search/bulk" \
  -H "Content-Type: application/json" \
  -d '{"tickers": ["AAPL","MSFT","NVDA","TSLA"], "form_type": "8-K", "limit_per_ticker": 100}'

/api/v1/stocks — 시장 현황 (Yahoo Finance 실시간)

현재 DB 보유: 없음. 실시간 스크래핑 전용.

엔드포인트 데이터 캐시 TTL
/stocks/most-active 실시간 상위 ~170 종목 1시간
/stocks/52-week-gainers 실시간 상위 ~1350 종목 1시간
/stocks/trending most-active + gainers 결합 30분

과거 데이터 조회 불가. 시계열 추적이 필요하면 주기적으로 /price 엔드포인트를 통해 개별 종목 가격을 저장하는 별도 배치 작업 필요.

/api/v1/overlay — Attention Overlay

현재 DB 보유:

데이터 보유 범위
Overlay score (feature records) 2026-03-17 ~ 현재, 50 심볼
뉴스 헤드라인 2026-02-24 ~ 현재
Wikipedia 페이지뷰 2015-12-26 ~ 현재 (풍부)
YouTube 멘션 서비스 시작 이후
Google Trends 서비스 시작 이후

조회 파라미터:

  • /{symbol}: 최신 composite score
  • /{symbol}/history?days=N: 스코어 시계열 (최대 365일)
  • /{symbol}/headlines?hours=N: 뉴스 (최대 168시간)
  • /{symbol}/wiki?days=N: Wikipedia 페이지뷰 (최대 90일)
  • /{symbol}/crowding: FINRA 기반 crowding 지표

지원 심볼: 기본 50개 (TOP_50_SYMBOLS). 그 외 심볼은 파이프라인 트리거 필요.

과거 데이터 백필: Overlay score는 실시간 수집 기반으로 과거 소급 생성 불가. Wikipedia 페이지뷰 (/wiki)는 2015년부터 조회 가능.

# 파이프라인 수동 트리거 (신규 심볼 추가 시)
POST /api/v1/overlay/admin/trigger-pipeline

# 특정 심볼의 헬스 상태 확인
GET /api/v1/overlay/admin/health

백필 우선순위 권장 사항

우선순위 대상 이유 예상 소요 시간
🔴 높음 FINRA 1년치 (2025년) z-score 계산 윈도우(30일)가 너무 짧아 신호 품질 저하 20-40분
🟡 중간 FINRA 2년치 (2024년) 더 긴 추세 분석 가능 1-2시간
🟢 낮음 Alpaca 데이터 Yahoo Finance와 중복, API 키 필요 필요시

FINRA 권장 백필 스크립트

# 1단계: 2025년 (가장 중요)
curl -X POST "http://localhost:18001/api/v1/finra/admin/ingest?start_date=2025-01-02&end_date=2025-12-31"

# 2단계: 2026년 공백 구간
curl -X POST "http://localhost:18001/api/v1/finra/admin/ingest?start_date=2026-01-02&end_date=2026-02-09"

# 3단계 (선택): 2024년
curl -X POST "http://localhost:18001/api/v1/finra/admin/ingest?start_date=2024-01-02&end_date=2024-12-31"

현재 DB 상태 확인 쿼리

-- 각 테이블 데이터 범위 확인
SELECT 'price_data' AS tbl, MIN(date)::date, MAX(date)::date, COUNT(DISTINCT date::date) AS days, COUNT(DISTINCT ticker) AS tickers FROM price_data
UNION ALL
SELECT 'finra_short_volume', MIN(date)::date, MAX(date)::date, COUNT(DISTINCT date::date), NULL FROM finra_short_volume
UNION ALL
SELECT 'sec_filings', MIN(filing_date)::date, MAX(filing_date)::date, COUNT(DISTINCT filing_date::date), COUNT(DISTINCT ticker) FROM sec_filings
UNION ALL
SELECT 'overlay_feature_records', MIN(as_of_ts)::date, MAX(as_of_ts)::date, COUNT(DISTINCT as_of_ts::date), COUNT(DISTINCT symbol) FROM overlay_feature_records
ORDER BY tbl;