주기성 재무 데이터 API 설계: 연간, 분기, YTD, LTM 구분

재무 API에서 가장 자주 헷갈리는 값이 연간, 분기, YTD, LTM이다. 모두 매출이나 이익 같은 같은 지표를 다루지만 질문이 다르다. “지난 회계연도 전체”, “이번 분기”, “올해 누적”, “최근 12개월”은 같은 엔드포인트로 묶더라도 응답 메타가 달라야 한다.

주기성 재무 데이터 API 설계: 연간, 분기, YTD, LTM 구분 핵심 구조도

주기별로 답하는 질문

period_type	질문	주의할 점
annual	한 회계연도 전체 실적	결산월이 다른 기업 비교
quarterly	해당 분기 실적	누적 값과 혼동
YTD	연초부터 현재 분기까지	분기 기업과 연간 기업 비교
LTM	최근 12개월 합산	수정 보고서 반영 시점

LTM 계산은 분기 데이터 품질에 의존한다

ltm_revenue = revenue_q0 + revenue_q1 + revenue_q2 + revenue_q3

if any quarter is missing:
    return value_status = 'incomplete'

응답에 꼭 넣을 메타

값만 주면 사용자는 기준을 추측하게 된다. period_type, fiscal_period, currency, unit, filed_at, value_status를 함께 내려주는 편이 안전하다.

API 설계 팁

• period_type을 문자열 옵션으로 받되 기본값을 숨기지 않는다.
• 누적 값과 단일 분기 값을 같은 컬럼명으로 돌려주지 않는다.
• 계산된 LTM에는 source=derived 같은 표시를 남긴다.

함께 보면 좋은 글

• 분기 재무 데이터 구축 방법
• 시계열 데이터 조회 API 설계