거시경제 데이터 API 설계: 스냅샷과 빌드 날짜 관리

거시경제 지표는 한 번 발표되면 끝나는 데이터가 아니다. 고용, 물가, GDP 같은 지표는 수정 발표가 나오고, 과거 값이 바뀐다. 그래서 API가 최신 값만 돌려주면 당시 관점의 분석을 재현하기 어렵다.

거시경제 데이터 API 설계: 스냅샷과 빌드 날짜 관리 핵심 구조도

두 날짜를 분리한다

날짜	의미	예시
observation_date	지표가 가리키는 기간	2025-03
release_date	처음 공개된 날짜	2025-04-05
vintage_date	사용자가 조회하는 기준일	2025-06-01
build_date	내부 배치가 만든 날짜	2025-06-02

스냅샷 조회의 기본 형태

GET /macro/cpi?observation_start=2020-01&vintage_date=2024-12-31

return latest row where release_date <= vintage_date

백테스트에서 필요한 값

최신 수정치가 아니라 그날 알 수 있었던 값이다. 이 기준을 지키지 않으면 거시 지표 기반 전략은 성과가 과대평가되기 쉽다.

API 응답에 넣을 메타

• value_status: preliminary, revised, final 중 하나를 표시한다.
• source_release_id를 남겨 원천 발표 자료로 되돌아갈 수 있게 한다.
• 응답에는 observation_date와 vintage_date를 모두 포함한다.

실전 적용 포인트

거시경제 지표는 최신 값만 저장하면 과거 판단을 재현하기 어렵다. 고용, 물가, GDP처럼 나중에 수정되는 지표는 발표 당시의 값과 수정 후의 값을 함께 다뤄야 한다.

API를 설계할 때 observation_date와 vintage_date를 분리하면 사용자가 당시 알 수 있었던 정보만 조회할 수 있다. 이 구조가 있어야 백테스트에서 미래 수정값을 몰래 쓰는 문제를 줄일 수 있다.

• 관측일, 발표일, 수정 기준일을 분리한다.
• 응답에는 preliminary, revised, final 상태를 포함한다.
• 백테스트는 vintage_date 기준 조회를 기본값으로 둔다.

함께 보면 좋은 글

• 환율 데이터 수집 설계
• 분기 재무 데이터 구축 방법