データ規約

単位

通貨

• 韓国株はウォン(KRW)、米国株はドル(USD)で返します。相互の換算は行いません。
• 配当など通貨が混在しうる値には、currency フィールドを併せて返します。
• PRO API の業績差異表(/earnings/{symbol}/variance)では、通貨や基準が異なる場合は差異(%)を計算せず、reasons に理由を記載します。

会計期間と暦の期間

• 財務の値は各社の会計期間に従います。韓国の上場企業の多くは12月決算ですが、米国企業は会計年度が暦年と異なる場合があります(例: 9月に終わる会計年度)。fiscal_year と period を併せて確認してください。
• PRO API の期間パラメータは、FY2027Q2、2026 3분기(第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)は、タイムゾーン変換をせずにそのまま読んでください。韓国のデータは韓国の日付、米国の開示・決算スケジュールは米国現地の日付です。日付文字列を0時の時刻に変換してからタイムゾーンを適用すると、1日ずれることがあります。
• 1日のクォータと使用量の日付(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 を選べる一覧で値を省略すると、1つの市場だけを契約しているアカウントではその市場が既定値になります。市場が混在するニュースフィードは契約中の市場の記事だけを返します。

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・q3_report(四半期報告書)、米国は 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 フィルターは銘柄タグが検証された記事だけを返します。そのため 1 ページが limit より短いことがあるので、has_more・next_cursor をたどってください。同じ記事の再配信(近似重複)は 1 ページで 1 件に絞ります。

株価(/quotes)

• data.valuation は /companies/{symbol}/metrics の valuation と同じ計算です(basis・eps_basis — 韓国の EPS・PER は親会社株主帰属純利益基準)。0 で届いた該当なしの値は null です。
• 最上位フィールド(symbol・price・fundamentals …)は従来互換用(非推奨)で、値・単位は従来のままです(fundamentals.debt_ratio は比率 0.311 = 31.1%)。新しいコードは data を読んでください。

Data API · エラーコード

空の値と銘柄コード

• 値を取得できない場合は null です。0 とは区別してください。
• 韓国株は6桁のコード(例: サムスン電子 · 005930)、米国株はティッカー(例: アップル · AAPL)を使います。エンドポイントごとの対応市場はリファレンスに記載しています。