韓国オープンデータAPIキーの取得と設定 (DART · ECOS · KRX · KOSIS · 法制処 · 公共データポータル)

この付録では、国別スコープの k-* スキルが利用する韓国の公共オープンデータAPI — 金融監督院のDART電子公示、韓国銀行経済統計システム（ECOS）、韓国取引所（KRX）データマーケットプレイス、法制処の国家法令情報センター、統計庁のKOSIS国家統計ポータル、公共データポータル（data.go.kr） — のキーを取得し、環境変数として設定する方法を説明します。

1. 概要

このワークスペースには、韓国の公共データを照会する国別スコープ（KR）スキルが6つ含まれています。k-dartは韓国金融監督院（금융감독원、FSS）が運営する電子公示システムDARTの、k-ecosは韓国銀行ECOSのマクロ・金融統計システムの、k-krxはKRX取引所の市場データの、k-lawは法制処（법제처、MOLEG）の国家法令情報センター（국가법령정보센터）の、k-kosisは統計庁（통계청、KOSTAT）のKOSIS国家統計ポータル（국가통계포털）の、k-opendataは公共データポータル（data.go.kr）のOpen APIを呼び出します。すべてのk-*スキルはリクエスト直前に環境変数からキーを読み込むため、利用前に各サービスのキーを取得して設定しておく必要があります。

6つのサービスはいずれも無料で、個人開発者でも登録手続きを済ませればすぐに利用できます。ただし承認にかかる時間はサービスごとに異なります — DARTとECOSは即時発行、国家法令情報センターは1–2営業日、KRXと公共データポータルの一部データセットは管理者承認が必要、KOSISは公式な基準が文書化されていないためポータルの掲示板で確認します。

2. APIキー一覧

取得対象のサービスを表にまとめます。詳細な手続きは各サービスのセクションを参照してください。

4. DART電子公示API

DARTは韓国金融監督院（금융감독원）が運営する電子公示システムのOpen APIです。上場企業の公示リストから企業概況、財務諸表、主要事項報告までを機械可読な形式で提供するため、企業分析エージェントのデータソースとして利用できます。

取得方法

1. opendart.fss.or.kr の会員登録ページ でアカウントを作成します。
2. ログイン後、認証キー申請メニューからOpen API認証キーを発行します。
3. 発行されたキー（40文字）を安全な場所に保管します — マイページで再確認できます。

認証キーは即時発行で、承認待ちはありません。

リクエスト方法

• キーの送信 — すべてのリクエストで、40文字の認証キーを crtfc_key パラメータとして渡します。
• 1日の上限 — 1日あたり約20,000リクエスト。超過するとステータスコード 020 が返ります。
• 固有番号が必要 — 企業別エンドポイントのほとんどは8桁の corp_code を要求します。corpCode.xml（固有番号ファイル）をダウンロードし、社名で検索して確認します。

主なステータスコードは次のとおりです。

照会できる内容

• 公示検索（공시검색）— 日付・企業・報告書種類別の公示リスト
• 企業概況（기업개황）— 会社概要、業種、資本金などの基本情報
• 財務諸表（재무제표）— 単一・複数企業の主要勘定と財務諸表
• 主要事項報告（주요사항보고）— 無償株式発行、資本変動などの主要報告

5. ECOS経済統計システムAPI

k-ecos は韓国銀行経済統計システム（ECOS）を照会します。基準金利、為替レート、通貨量、GDP、100대 통계지표（主要100統計指標）のクイック照会まで、韓国のマクロ・金融統計の一次ソースです。

取得方法

• サインアップなしで試せます — 公開デモキー（文字どおり sample）が、リクエストあたり10行までのスモークテストとして動作します。実利用には ecos.bok.or.kr で自分のキーを発行し（マイページ > 認証キー申請）、ECOS_API_KEY に保存してください。

リクエスト方法

• 周期コードは別のアルファベットを使います — 주기（周期）セグメントには A/S/Q/M/SM/D を使います。他のガイドからよくコピーされる YY/QQ/MM/DD 形式ではありません。誤ったアルファベットは ERROR-100 の最も多い原因で、日付形式も周期と正確に一致させる必要があります（A は 2024、Q は 2024Q1、M は 202401、D は 20240101、半年は 2024S1、半月は 202401S1）。

6. KRXデータマーケットプレイスAPI

k-krx は韓国取引所（KRX）データマーケットプレイスのOPEN APIを照会します。コスピ・コスダック・コネクスの日次取引、銘柄マスタ、ETF/ETN/ELW時情、指数、債券、デリバティブ、一般商品を7カテゴリ / 31サービスの規模で提供します。

取得方法

• 公開デモキーは存在しません — プレースホルダーキーは 401 Unauthorized Key で拒否されます。キー発行には openapi.krx.co.kr のポータル登録に加え、管理者承認とサービス別利用申請が必要なため、データが必要になる時点より余裕を持って申請してください。

リクエスト方法

• キーはクエリ文字列ではなくヘッダーで渡します — すべてのリクエストが AUTH_KEY ヘッダーにキーを載せて送ります:

curl -fsS -H "AUTH_KEY: $KRX_API_KEY" \
  'https://data-dbg.krx.co.kr/svc/apis/sto/stk_bydd_trd.json'

エラーは {"respCode":"...","respMsg":"..."} 形式のベアJSONで返ります — デバッグ時は両方のフィールドをそのまま確認してください。

7. 国家法令情報センターAPI

国家法令情報センター（국가법령정보센터）は、韓国法制処（법제처）が運営する法令統合ポータルです。現行法令の本文に加え、判例・行政規則・自治法規までOpen APIで提供しており、法令検索・要約スキルのデータソースとして使います。

申請方法

open.law.go.kr で会員登録した後、上部メニュー OPEN API > 利用申請から利用するAPIを選んで申請します。承認には通常1–2営業日かかります。

OC識別子

法令ポータルは個別のキー文字列を発行しません。代わりに、登録時に使用したメールID全体（例: myname@example.com）がOC識別子になります。環境変数 LAW_API_OC にそのメールIDをそのまま保存し、リクエスト時に OC= パラメータで渡します。

照会できる内容

• 現行法令（현행법령）— 法律・施行令・施行規則の本文と検索
• 判例（판례）— 大法院・憲法裁判所の決定
• 行政規則・自治法規（행정규칙·자치법규）— 訓令・例規、条例・規則
• 法令解釈例・条約（법령해석례·조약）— 権威ある解釈事例と国際条約

8. KOSIS国家統計ポータルAPI

KOSIS（국가통계포털）は韓国統計庁（통계청）が運営する国家統計ポータルです。人口・経済・社会全般の公式統計表をOpen APIで提供しており、統計照会・時系列分析スキルのデータソースとして使います。

申請方法

kosis.kr/openapi で会員登録した後、利用申請メニューからOpen APIの利用を申請します。

リクエスト方法

• キーの送信 — 環境変数 KOSIS_API_KEY にキーを保存し、リクエスト時に apiKey= パラメータで渡します。
• エラーレスポンス — パラメータエラーは {"err":"21"}、該当データなしは {"err":"30"} の形式で返ります。
• コードの確認 — 統計表コード（objL1）や項目コード（itmId）がリクエストごとに必要で、統計リスト照会を段階的にたどって確認します。

照会できる内容

• 統合検索（통합검색）— 統計表・項目のキーワード検索
• 統計リスト（통계목록）— 分類別の統計表一覧
• 統計データ（통계자료）— 実際の数値データ
• 統計説明（통계설명）— 統計表の定義・単位・注記

9. 公共データポータル（data.go.kr）API

k-opendata は公共データポータル（공공데이터포털、data.go.kr）を照会します。このポータルは、数十の韓国政府機関のOpen APIを1つのアカウント・サービスキー体系にまとめた共用ゲートウェイです。ポータルのサービスキー1つですべてのデータセットの認証を通過しますが、実際に呼び出すには個別のデータセット（機関 + API）ごとに別途の利用申請が必要です。本付録では、代表例として韓国関税庁（관세청）の貿易統計APIを扱います — KOSISでは取得できないHSコード単位の輸出入実績が必要な場合に使用します。

取得方法

1. data.go.kr で会員登録し、一般認証キー（エンコーディング/デコーディング）を発行します — 承認なしで即時発行されます。
2. このサービスキーはポータル全体で再利用されますが、実際に呼び出したい個別のデータセットの詳細ページで、別途利用申請を提出する必要があります。
3. データセットごとの承認所要時間は機関によって異なるため、マイページの開発アカウント / 運用アカウントの状態で承認状況を確認します。

発行されたサービスキーは DATA_GO_KR_API_KEY に保存します。

照会できる内容（韓国関税庁 貿易統計）

• 品目別・国別輸出入実績 — HSコード単位の国・期間別輸出入金額・重量
• 全体/地域別輸出入総計 — 全国または地域単位の貿易収支動向

10. 環境変数の設定

発行されたキーは、プロジェクトルートの .env.sample を .env にコピーして設定します。韓国関連のキー — DART_API_KEY、ECOS_API_KEY、KRX_API_KEY、LAW_API_OC、KOSIS_API_KEY、DATA_GO_KR_API_KEY — は、いずれも # >>> country-scoped:KR マーカーブロックに最初から記載されています — 値を埋めるだけで、行を重複して追加しないでください。

cp .env.sample .env

# country-scoped:KR ブロック — 使うキーを実際の値に置き換えます
DART_API_KEY=発行された-40文字-の認証キー
ECOS_API_KEY=発行された-ECOS-キー          # 公開デモキー: sample
KRX_API_KEY=発行された-KRX-キー
LAW_API_OC=登録-メールID@example.com
KOSIS_API_KEY=発行された-KOSIS-キー
DATA_GO_KR_API_KEY=発行された-公共データポータル-サービスキー

Windows（PowerShell）では現在のセッションに設定し、必要ならユーザー変数として恒久的に保存します。

$env:DART_API_KEY="発行された-40文字-の認証キー"
$env:ECOS_API_KEY="発行された-ECOS-キー"
$env:KRX_API_KEY="発行された-KRX-キー"
$env:LAW_API_OC="登録-メールID@example.com"
$env:KOSIS_API_KEY="発行された-KOSIS-キー"
$env:DATA_GO_KR_API_KEY="発行された-公共データポータル-サービスキー"

# 恒久保存（ユーザー変数）— 新しいターミナルでも保持されます
[System.Environment]::SetEnvironmentVariable("DART_API_KEY", "発行された-40文字-の認証キー", "User")

macOS / Linuxでは、シェルプロファイルに export 行を追加します。

export DART_API_KEY="発行された-40文字-の認証キー"
export ECOS_API_KEY="発行された-ECOS-キー"
export KRX_API_KEY="発行された-KRX-キー"
export LAW_API_OC="登録-メールID@example.com"
export KOSIS_API_KEY="発行された-KOSIS-キー"
export DATA_GO_KR_API_KEY="発行された-公共データポータル-サービスキー"

11. 動作確認

キーが正しく設定されたか、サービスごとに簡単なcurl呼び出しで確認します。各コマンドはいずれも環境変数を読むため、設定した同じターミナルで実行してください。

ECOS — 主要100統計指標（公開 sample キーで動作、サインアップ不要）

# ECOS — 100 key indicators (public demo key works)
curl -fsS --get 'https://ecos.bok.or.kr/api/KeyStatisticList/sample/json/kr/0/10/'

期待される結果: 為替レート・基準金利・成長率などの最新の主要指標を含むJSONが出力されます。自分のキーを発行したら、sample を $ECOS_API_KEY に置き換えてください。

DART — 企業概況（サムスン電子）

# DART — company overview (Samsung Electronics)
curl -fsS --get 'https://opendart.fss.or.kr/api/company.json' \
  --data-urlencode "crtfc_key=$DART_API_KEY" \
  --data-urlencode 'corp_code=00126380'

期待される結果: status が "000" のJSONで、サムスン電子の企業概況が出力されます。

法令 — 法令検索

# LAW — statute search
curl -fsS --get 'https://www.law.go.kr/DRF/lawSearch.do' \
  --data-urlencode "OC=$LAW_API_OC" \
  --data-urlencode 'target=law' \
  --data-urlencode 'type=JSON' \
  --data-urlencode 'query=개인정보보호법' \
  --data-urlencode 'display=10'

期待される結果: LawSearch レスポンスのJSONが出力され、totalCnt が1以上になります（個人情報保護法の検索結果）。

KOSIS — 統計リスト

# KOSIS — statistics list
curl -fsS --get 'https://kosis.kr/openapi/statisticsList.do' \
  --data-urlencode "apiKey=$KOSIS_API_KEY" \
  --data-urlencode 'method=getList' \
  --data-urlencode 'vwCd=MT_ZTITLE' \
  --data-urlencode 'parentId=A' \
  --data-urlencode 'format=json'

期待される結果: 統計リスト行を含むJSON配列が出力されます。

12. トラブルシューティング

よくある症状と対処方法をまとめます。

13. ライセンスと出典表記

DART・法制処・KOSIS・公共データポータルの4つの公共サービスが提供するデータは、韓国の公共データ著作物利用許諾 コングヌリ（공공누리、KOGL）ライセンスで提供されます。ECOSとKRXのAPIは、それぞれの利用規約（경제통계 Open API 이용약관 / KRXデータマーケットプレイス利用規約）に従います。レポートやエージェントの成果物にデータを引用・再構成する場合は、出典（例: 出典: 韓国金融監督院 DART電子公示）を明記する必要があります。著作物タイプ別の表記方法はコングヌリ公式サイトで確認してください。