데이터 규약

단위

통화

• 국내 종목은 원(KRW), 미국 종목은 달러(USD)로 냅니다. 서로 환산하지 않습니다.
• 배당처럼 통화가 섞일 수 있는 값은 currency 필드를 함께 줍니다.
• PRO API 실적 차이표(/earnings/{symbol}/variance)는 통화·기준이 다르면 차이(%)를 계산하지 않고 reasons에 이유를 적습니다.

회계 기간과 달력 기간

• 재무 값은 회사의 회계 기간을 따릅니다. 국내 상장사는 대부분 12월 결산이지만, 미국 기업은 회계연도가 달력 연도와 다를 수 있습니다(예: 9월에 끝나는 회계연도). fiscal_year와 period를 함께 읽으세요.
• PRO API의 기간 파라미터는 FY2027Q2, 2026 3분기, 2026(연간)처럼 씁니다.
• 국내 2~4분기 값은 누적 보고서에서 직전 누적을 빼서 만들 수 있습니다. 이때 derived_from에 뺀 보고서를 적습니다. 잠정실적 공시에서 온 값은 preliminary: true입니다.
• 연결/별도는 fs로 구분합니다. 국내 EPS·PER·ROE는 지배주주 순이익 기준이고 eps_basis(controlling · total)로 표시합니다.

날짜와 시각

• 시각(as_of, published_at 등)은 ISO 8601 UTC 문자열입니다(끝이 Z). 한국시간은 9시간을 더합니다.
• 날짜만 있는 값(YYYY-MM-DD)은 시간대 변환 없이 그대로 읽으세요. 국내 데이터는 한국 날짜, 미국 공시·실적 일정은 미국 현지 날짜입니다. 날짜 문자열을 자정 시각으로 바꾼 뒤 시간대를 적용하면 하루가 밀릴 수 있습니다.
• 하루 쿼터와 사용량의 날짜(X-Quota-Period, usage.day)는 한국시간 기준입니다.
• PRO API 시세는 session과 regular.label(정규장 현재가 · 정규장 종가)로 어느 세션 값인지 알려 줍니다. 프리·애프터·데이마켓 체결가는 extended에 따로 둡니다.

출처와 기준 시점

PRO API의 데이터 응답은 모두 같은 틀을 씁니다.

{
  "data": { "...": "엔드포인트별 값" },
  "as_of": "2026-10-21T06:35:10.000Z",
  "sources": [
    { "name": "DART", "url": "https://dart.fss.or.kr/dsaf001/main.do?rcpNo=20261021000123" }
  ],
  "disclaimer": "…",
  "meta": { "unit_note": "국내 억원 · 미국 백만달러" }
}

• as_of: 값의 기준 시점입니다. 응답을 만든 시각과 다를 수 있습니다(예: 시세 기준일).
• sources: 원문 링크 목록입니다. DART·SEC 원문과 Phoenix AI 페이지 링크만 담습니다.
• 재무 행에는 report(보고서명), rcept_date(접수일), source_url(원문 링크)이 붙습니다.
• AI 공시 요약은 source로 저장본(cache)인지 이번 요청에서 만든 것(generated)인지 알려 줍니다.
• Data API의 공시 응답은 접수번호와 원문 링크를, 뉴스는 언론사명(publisher)과 원문 열기 링크를 줍니다.

데이터 범위(시장)

• 계약에 따라 한국(KR) · 미국(US) 데이터를 골라서 제공합니다. 둘 다 계약할 수 있습니다. 일본(JP) · 중국(CN) 데이터는 준비 중입니다.
• 계약한 시장은 GET /key의 markets(지금 계약할 수 있는 시장 markets_available, 준비 중 markets_coming_soon), 모든 응답의 X-Markets 헤더, 개발자 콘솔의 데이터 범위 카드에서 확인합니다.
• 시장은 종목 코드(국내 6자리 = KR, 미국 티커 = US)나 market 파라미터로 정해집니다. 계약하지 않은 시장은 403 MARKET_NOT_ENTITLED, 일본·중국은 400 MARKET_NOT_AVAILABLE입니다.
• market을 고르는 목록에서 값을 생략하면, 한 시장만 계약한 계정은 그 시장이 기본값입니다. 시장을 섞는 뉴스 피드는 계약한 시장의 기사만 돌려줍니다.

Data API 응답 모양

• 한 문서: { data, meta }. 목록: { data, next_cursor, has_more, meta }. 다음 페이지는 next_cursor를 같은 필터로 그대로 보냅니다.
• meta에는 늘 as_of(응답 시각)가 있고, 회사 엔드포인트(/companies/{symbol}/…)는 disclaimer·unit_note·page_url도 줍니다.
• 오류는 늘 { error: { code, message, docs } }입니다. 위 PRO API 틀(sources 포함)과 다르니 섞어 읽지 마세요.

엔드포인트별 단위·통화

기계용 코드

• period_code: 연간 FY2025 · 분기 2026Q3 · 누적 2025YTDQ2(상반기)·2025YTDQ3(1~3분기). 회사 회계연도 기준입니다(미국은 period_end로 실제 날짜를 확인하세요).
• account_code: 아래 계정 코드. fs_code: CFS(연결)·OFS(별도). unit_code: KRW_EOK·USD_MIL·USD·KRW·SHARES_MIL.
• report_code: 국내 annual_report(사업보고서)·half_year_report(반기보고서)·q1_report(1분기보고서)·q3_report(3분기보고서), 미국은 SEC 서식(10-K·10-Q·20-F·8-K …).
• 한국어 칸(account·period·report·name)은 화면용 표시 문자열입니다. 정렬·조인·필터에는 코드 칸을 쓰세요.

계정 코드

/companies/{symbol}/financials의 account 파라미터와 응답 account_code입니다. 영문 코드는 그 계정만 정확히, 한국어 이름은 부분일치로 찾습니다(예: 순이익 → 당기순이익·지배주주순이익). 쉼표로 여러 개를 줄 수 있고, 모르는 영문 낱말은 400 BAD_REQUEST입니다.

기간 입력(period)

• 재무제표: 연간 FY2025·2025, 분기 2026Q2·FY2026 Q2·Q2 2026, 국내 누적 2025H1(=2025YTDQ2)·2025YTDQ3, 그리고 latest_quarter·annual·quarterly. 한국어(2025 연간·2026 2분기·2025 반기 누적)도 받습니다.
• 컨센서스·가이던스: 2026Q3·FY2027Q2(분기), FY2026·2026(연간), last·next(지난·다음 분기).
• 그 밖의 값은 400 BAD_PERIOD입니다. 응답의 period_code를 그대로 넣을 수 있습니다.

삼성전자 · 005930

curl -sG "https://api.chickstockfi.com/openapi/v1/companies/005930/financials" \
  -H "Authorization: Bearer $PHOENIX_API_KEY" \
  --data-urlencode "account=revenue,operating_income" \
  --data-urlencode "period=2026Q2" \
  --data-urlencode "fs=CFS"

재무제표 정렬과 페이지

• 정렬: 회계연도·분기 최신순(같은 해는 연간 → 4분기 → 1분기, 누적은 같은 분기 뒤) → 계정(재무제표 순서) → 연결(CFS) 먼저 → 공시 원장 먼저.
• 페이지: limit(기본 100, 최대 200) + cursor. 계정·기간을 생략하면 원장 전체를 최신 기간부터 돌려주고, 나머지는 next_cursor로 이어 받습니다(meta.total = 전체 줄 수). 줄은 data.rows에 있습니다.
• fs=CFS·fs=OFS로 연결·별도를 고릅니다(국내). 미국 줄은 CFS입니다.

회사 IR 자료로 채운 기간

• 공시 원장(DART·SEC) 값이 먼저입니다. 원장에 없는 (계정, 기간)만 회사 IR 자료로 채우고 source가 기업 IR 자료입니다.
• 채우는 계정은 매출액·영업이익·당기순이익·부채총계·자본총계·유동자산·유동부채뿐입니다. 그래서 IR 자료로 채운 기간에는 일부 계정만 있습니다. 어떤 기간·계정인지는 meta.partner_filled_periods·partner_filled_accounts에 있습니다.
• IR 자료 줄은 공시가 아니라서 report·report_code·filed_date·source_url·period_end가 null입니다.

컨센서스와 가이던스

• 컨센서스는 국내 매출·영업이익, 미국 매출만 줍니다. meta.metrics가 그 시장에서 실제로 주는 지표입니다.
• 발표 완료 기간의 vs_consensus_pct는 발표일(reported_on) 이전에 관측한 컨센서스(consensus_at_report)가 있을 때만 계산합니다. 없으면 null이고 comparison_status로 이유를 알려 줍니다 — compared · basis_unconfirmed(기준 일치 미확인) · no_pre_report_estimate(발표 전 값이 없거나 발표일을 모름) · no_actual · upcoming.
• 미국 일부 기간은 원천이 발표 시각을 주지 않아 reported_on이 null입니다. 그때는 발표 직전 값을 고르지 않습니다.
• 가이던스(/companies/{symbol}/guidance)의 value·low·high는 원·달러 그대로이고 unit·unit_scale(1)이 그 단위를 말합니다. 표로 보일 때의 단위는 display_unit·display_scale입니다(값 ÷ display_scale = display_unit 단위 숫자).

공시 목록 거르기(미국)

• /companies/{symbol}/disclosures에서 미국 종목은 form=10-K,10-Q,8-K(그 서식만, 10-K는 정정 10-K/A까지)·exclude_forms=424B2,SC 13G(그 서식 빼고)로 거릅니다. 쉼표로 최대 10개입니다.
• 거르지 않으면 대량으로 반복되는 서식(424B2·SC 13G 등)은 목록의 일부만 차지하도록 줄입니다. 국내 종목에 이 필터를 주면 400 BAD_REQUEST입니다.
• 모든 공시 줄에 report_code(국내 정기보고서 코드·미국 서식)가 있습니다.

뉴스 범위

• market=KR은 국내 언론 기사(한국어), market=US는 미국 기사(해외 언론의 영문 기사·기업 보도자료·SEC 공시 속보)입니다. 생략하면 둘 다 옵니다. Phoenix AI가 이미 모아 둔 기사만 돌려줍니다.
• 미국 영문 기사는 title이 원문이고 title_ko가 Phoenix AI 번역입니다(없으면 null). lang은 title의 언어입니다.
• publisher는 언론사 이름입니다. 집계 서비스 이름이 언론사 자리에 오면 해외 언론(해외)·뉴스(국내)로 표시합니다.
• symbol 필터는 종목 태그가 검증된 기사만 줍니다. 걸러진 만큼 한 페이지가 limit보다 짧을 수 있으니 has_more·next_cursor를 따라가세요. 같은 기사의 재송고(근사 중복)는 한 페이지에서 하나만 남깁니다.

시세(/quotes)

• data.valuation은 /companies/{symbol}/metrics의 valuation과 같은 계산입니다(basis·eps_basis — 국내 EPS·PER은 지배주주 순이익 기준). 0으로 온 해당 없음 값은 null입니다.
• 최상위 칸(symbol·price·fundamentals …)은 예전 호환용(deprecated)이라 값·단위가 예전 그대로입니다(fundamentals.debt_ratio는 비율 0.311 = 31.1%). 새 코드는 data를 읽으세요.

Data API · 오류 코드

빈 값과 종목 코드

• 값을 구할 수 없으면 null입니다. 0과 구분하세요.
• 국내 종목은 6자리 코드(예: 삼성전자 · 005930), 미국 종목은 티커(예: 애플 · AAPL)를 씁니다. 엔드포인트별 지원 시장은 레퍼런스에 적혀 있습니다.