2.주식 데이터 API, 숫자 검수 6단계

수집부터 팩트체크와 통과·중단까지 보여주는 개념도

주식 데이터 API 카드뉴스의 뉴스 칸을 매일 세 개씩 채우기로 했습니다. 그런데 새 기사가 없는 아침이 오자 전날 링크를 다시 넣었어요. 제목을 조금 줄여 쓰니 새 뉴스처럼 보였습니다.

수집 기능이 부족해서 생긴 문제가 아니었어요. 새 뉴스 없음을 정상 상태로 기록할 칸이 없었던 게 원인이었습니다. 시세도 마찬가지였습니다. 전일 종가와 장중 값, 달러 원값과 원화 환산값을 구분할 스키마가 없으면 데이터가 많아져도 다시 확인하기 어렵습니다.

그래서 이번에는 API 연결을 늘리지 않았습니다. 먼저 값의 뜻과 멈춤 조건을 적는 작은 데이터 사전부터 만들었습니다.

핵심 요약

카드에 넣을 값은 원값·종류·통화·시장 시각·출처·상태를 한 묶음으로 저장합니다. 계산값은 원값을 덮어쓰지 않고, 누락·오래됨·중복·수집 실패를 서로 다른 상태로 기록합니다.

이 글은 투자 판단을 대신하지 않습니다. 관심 종목 정보를 정리할 때 어떤 값이 어디서 왔는지 사람이 다시 확인하기 위한 업무 설계입니다.

목차

1. 뉴스 세 건을 채우려다 전날 기사를 다시 넣었다
2. 데이터 공급자보다 선택 기준을 먼저 정한다
3. 카드뉴스 입력 스키마는 어떤 칸으로 만들까
4. 시장별 날짜와 시간대를 어떻게 분리할까
5. 뉴스 중복과 새 뉴스 없음을 어떻게 구분할까
6. 계산값과 원값을 왜 따로 보존할까
7. 공급자 후보는 무엇을 기준으로 비교할까
8. FACT_CHECK 대장은 왜 지우지 않을까
9. 오류·결측이면 어디에서 멈출까
10. 결론과 FAQ

1. 뉴스 세 건을 채우려다 전날 기사를 다시 넣었다

오전 8시 20분, 민은 관심 종목 세 개의 뉴스를 찾고 있었습니다. 첫 종목은 새 기사가 있었지만 나머지는 없었어요. 카드 모양을 맞추려고 전날 링크를 다시 넣는 순간, 자동화 목표가 이상해졌습니다.

세 칸을 채운다와 새 정보를 확인한다는 같은 일이 아니었습니다.

그날부터 뉴스 항목에 게시 시각, 원문 URL, 수집 시각, 검색 범위, 중복 상태를 남겼습니다. 새 뉴스가 없으면 no_new_item, API 호출 자체가 실패하면 error로 나눴어요. 빈칸이 보기 싫다는 이유로 오래된 기사를 오늘 기사처럼 쓰지 않기 위해서였습니다.

2026-08-04 DeepSearch 뉴스 API 공식 문서는 기업명·종목 코드·거래소·뉴스 게시일 등의 조건으로 검색할 수 있다고 설명한다.
2026-08-04 DeepSearch 공식 문서는 뉴스 콘텐츠 이용 시 관련 저작권 가이드를 확인하라고 안내한다.
출처: https://news.deepsearch.com/api
여기서 한 번 멈춰야 했습니다. 공급자를 바꾸기 전에 실패를 어떤 상태로 기록할지 먼저 정하지 않으면 같은 문제가 반복됩니다.

2. 데이터 공급자보다 선택 기준을 먼저 정한다

처음에는 무료 호출량이 많은 API를 찾았습니다. 하지만 가격표를 비교하기 전에 카드의 값이 무엇을 뜻하는지 정해야 했어요.
제가 먼저 적은 질문은 이렇습니다.

• 전일 종가인가, 장중 값인가?
• 원시값인가, 분할·배당을 반영한 조정값인가?
• 정규장 값인가, 장전·장후를 포함하는가?
• 값의 통화와 거래소 시간대는 무엇인가?
• 최신 값이 없으면 언제 생성을 멈추는가?

2026-08-04 Alpha Vantage 공식 문서는 TIME_SERIES_DAILY를 원시 일봉으로 설명하고, 조정 종가와 분할·배당 이벤트는 TIME_SERIES_DAILY_ADJUSTED에서 구분한다.
2026-08-04 Alpha Vantage 장중 문서는 정규장 외 시간 포함 여부와 원시값·조정값 선택 옵션을 안내한다.
출처: https://www.alphavantage.co/documentation/
특정 공급자가 무조건 낫다는 결론은 내리지 않았습니다. 같은 공급자 안에서도 엔드포인트와 플랜에 따라 조건이 달라질 수 있기 때문입니다.

3. 카드뉴스 입력 스키마는 어떤 칸으로 만들까

스키마란 카드에 넣기 전, 각 값의 이름과 뜻을 정한 입력 설계입니다.
최소 스키마는 다음 세 묶음으로 나눴습니다.

종목 식별

• instrument_id: 작업 안에서 쓰는 고정 ID
• symbol: 데이터 요청에 사용한 심볼
• exchange_mic: 거래소 식별 코드

시세 원값과 메타데이터

• price_raw: 제공사가 반환한 원값
• price_type: previous_close, intraday, adjusted_close 등의 종류
• currency: 원값의 통화
• market_timestamp: 시장 기준 시각과 오프셋
• exchange_timezone: 거래소 시간대
• collected_at: 수집 시각
• source_name, source_url: 출처

검수 상태

• status: ok, missing, stale, error
• reason: 누락·오래됨·오류 사유
• checked_at: 사람이 마지막으로 확인한 시각

2026-08-04 Twelve Data 공식 문서는 응답 메타데이터에 symbol, currency, exchange_timezone, exchange, mic_code를 포함한다고 설명한다.
출처: https://twelvedata.com/docs/currencies

원값·메타데이터·계산값의 3층 구조 개념도

필드가 많아 보여도 핵심은 단순합니다. 화면에 보이는 값과 다시 검증할 원자료를 섞지 않는 것입니다.

4. 시장별 날짜와 시간대를 어떻게 분리할까

한국에서 확인한 날짜와 거래소의 시장 날짜를 같은 값으로 저장하지 않습니다.
미국 시장의 데이터는 한국 아침에 보면 날짜가 다르게 느껴질 수 있어요. 화면에는 한국 시간을 보여주더라도 원본 시장 시각과 시간대는 남겨야 합니다.
2026-08-04 Twelve Data 공식 문서는 주식의 기본 시간대를 거래소 소재 시간대로 설명하며, 일·주·월 간격 데이터는 거래소 현지 시간 기준으로 반환된다고 명시한다.
NYSE 공식 페이지는 2026년 휴장일과 특정일 조기 종료 시간을 별도로 안내한다.
출처: https://twelvedata.com/docs/currencies

출처: https://www.nyse.com/trade/hours-calendars

그래서 어제라는 표현을 데이터 규칙에서 빼고 직전 거래일과 실제 날짜를 씁니다. 휴장일 다음 날에도 오래된 값을 새 값으로 오해하지 않게 됩니다.

5. 뉴스 중복과 새 뉴스 없음을 어떻게 구분할까

원문 URL이 같으면 중복으로 제외하고, 제목만 비슷하면 사람이 원문을 비교합니다.
뉴스 URL에는 추적용 매개변수가 붙을 수 있어 정규화한 URL도 함께 보관했습니다. 다만 제목 유사도만으로 같은 기사라고 단정하지 않았어요. 통신사 기사를 여러 매체가 전재했는지, 후속 보도인지 원문을 봐야 하기 때문입니다.
공시 사실은 뉴스 요약과 분리합니다. SEC EDGAR 공식 API는 제출 이력과 XBRL Company Facts 데이터를 제공하며 자동 접근은 SEC 정책을 따라야 한다. 공시를 근거로 쓰는 카드라면 제출 시각과 공시 원문 URL을 남깁니다.
출처: https://www.sec.gov/search-filings/edgar-application-programming-interfaces

새 뉴스가 없는 상태는 실패가 아닙니다. 검색 기간과 확인한 출처를 기록했다면 no_new_item이라는 정상 결과가 될 수 있어요. 반대로 API 오류는 새 뉴스가 없다는 뜻이 아니므로 이전 링크를 재사용하지 않고 중단합니다.

6. 계산값과 원값을 왜 따로 보존할까

등락률과 원화 환산값은 원값에서 다시 계산할 수 있도록 별도 영역에 둡니다.
원화 환산값만 남기면 어느 환율을 언제 적용했는지 알 수 없습니다. 등락률만 남기면 분모가 전일 종가였는지 다른 값이었는지 확인하기 어려워요.
계산값에는 다음을 붙였습니다.

• 계산식
• 입력한 원본 필드 ID
• 반올림 전 값
• 화면 표시값
• 계산 시각
• 환산이면 환율 원값·기준 시각·출처

분모가 없거나 두 값의 기준일이 다르면 계산하지 않습니다. 0%나 추정값으로 채우는 대신 중단 사유를 남겼어요.

7. 공급자 후보는 무엇을 기준으로 비교할까

가격보다 데이터 범위와 운영 부담을 공식 문서에서 먼저 확인합니다.

후보	공식 문서에서 볼 항목	운영 질문
Alpha Vantage	일봉·장중, 원시값·조정값, 세션 옵션	내가 받은 값은 어떤 종류인가?
Twelve Data	통화, 거래소, MIC, 시간대	원본 통화와 시장 시각을 저장하는가?
KRX·공공데이터포털	국내 시세 항목, 제공 방식, 갱신 주기	카드 시각에 쓸 수 있는 최신 기준일은 언제인가?
SEC EDGAR	제출 이력과 Company Facts	요약 뒤에 남길 공시 원문은 무엇인가?
뉴스 API 후보	게시일·종목·출처 범위, 이용 조건	새 뉴스 없음과 수집 실패를 구분하는가?

2026-08-04 KRX Data Marketplace 공식 안내는 개인 참고용 실시간 또는 지연시세정보 경로를 설명하며 20분 또는 종가 형태를 언급한다.
2026-08-04 공공데이터포털 금융위원회 주식시세정보 페이지는 시가·종가·고가·저가·거래량을 제공하고 갱신 주기를 일 1회로 표시한다.
출처: https://openapi.krx.co.kr/contents/OPP/DATA/OPPDATA003.jsp

출처: https://www.data.go.kr/data/15094808/openapi.do
제공사별 가격, 무료·유료 플랜, 호출 한도, 지원 시장, 실시간·지연 조건은 사용 직전 공식 문서에서 다시 확인해야 한다.
이 비교는 승자를 고르는 표가 아닙니다. 내 카드의 필수 필드를 안정적으로 채울 수 있는지, 조건이 바뀌었을 때 어디를 다시 확인할지 정하는 표입니다.
후보를 정한 뒤에도 공식 문서의 조건은 고정값으로 취급하지 않았습니다. 다시 확인할 문장을 별도 대장에 남겼습니다.

8.  대장은 왜 지우지 않을까

출처를 확인한 표식은 삭제하지 않고 다음 실행의 검수 목록으로 남깁니다.
한 번 확인한 문서도 플랜, 호출 한도, 지원 시장, 데이터 지연 조건이 바뀔 수 있어요. 표식을 지우면 다음 달에는 어떤 문장을 다시 봐야 하는지 놓치기 쉽습니다.

대장에는 주장, 기준일, 공식 URL, 마지막 확인 시각, 다음 확인 조건을 둡니다. 확인 완료는 영구 사실이라는 뜻이 아니라 그 기준일에 공식 출처를 읽었다는 기록입니다.

9. 오류·결측이면 어디에서 멈출까

필수 가격·통화·기준일이 맞지 않으면 카드 렌더링 전에 중단합니다.

• 필수 가격 누락: missing, 생성 중단
• 기대한 직전 거래일과 다름: stale, 생성 중단
• 통화 누락 또는 혼재: error, 계산 중단
• 새 뉴스 없음: no_new_item, 빈 상태를 표시하고 계속 가능
• 같은 원문 URL: duplicate, 제외
• 제목만 비슷함: review_needed, 사람 확인
• API 오류: 응답 상태와 재시도 횟수를 남기고 이전 값을 재사용하지 않음

뉴스 중복·결측·오류 상태를 나누는 결정 트리

멈추는 규칙을 먼저 정하니 빈 카드가 덜 불안했습니다. 빈칸은 이유를 설명할 수 있지만, 기준이 섞인 숫자는 카드만 보고 알아채기 어렵기 때문입니다.

10. 결론: 빈칸보다 위험한 것은 뜻이 없는 숫자다

주식 데이터 API 카드뉴스의 첫 성공 조건은 세 칸을 모두 채우는 것이 아닙니다. 카드의 숫자와 뉴스마다 무엇·언제·어디서를 다시 설명할 수 있는 상태가 먼저입니다.

관심 종목 하나로 시작해 원값, 종류, 통화, 시장 시각, 수집 시각, 출처, 상태 일곱 칸을 채워보세요. 조건이 맞지 않으면 카드 생성 전에 멈추는 것까지가 한 번의 정상 실행입니다.
다음 3편에서는 이 검수된 값을 모바일에서 읽히는 고정 카드 레이아웃과 하단 출처 영역에 넣습니다.

자주 묻는 질문

Q. 실시간 데이터면  검사가 필요 없을까?

필요합니다. 실시간·지연 조건, 거래 세션, 시장 시각, 수집 시각이 기대와 맞는지 확인해야 합니다.

Q. 뉴스가 없으면 카드 전체를 중단해야 할까?

카드의 필수 조건에 따라 정합니다. 뉴스가 선택 항목이라면 검색 범위와 no_new_item을 남기고 시세 카드만 만들 수 있습니다.

Q. 제목이 같으면 중복 기사인가?

제목 유사도는 후보를 찾는 기준일 뿐입니다. 원문 URL, 게시 시각, 본문과 출처를 사람이 비교해야 합니다.

Q. 무료 API와 유료 API 중 무엇이 더 안전할까?

가격만으로 안전성을 결정할 수 없습니다. 필요한 시장·시간대·신선도·조정 방식·이용 조건과 오류 응답을 공식 문서에서 확인하세요.

Q.  표식은 출처 확인 후 삭제해도 될까?

이 파이프라인에서는 삭제하지 않습니다. 기준일이 바뀌거나 조건이 변경됐을 때 다시 확인할 검수 목록으로 유지합니다.
이 글은 정보 정리 자동화 예시이며 투자 권유, 개인 맞춤 자문, 종목 추천, 수익률 예측이 아닙니다.
최종 업데이트: 2026년 8월 4일