付録D

韓国オープンデータAPIキーの取得と設定

この付録では、k-dart・k-law・k-kosis スキルが利用する韓国の公共オープンデータAPI — 金融監督院のDART電子公示、法制処の国家法令情報センター、統計庁のKOSIS国家統計ポータル — のキーを取得し、環境変数として設定する方法を説明します。

この付録で扱う内容

3つの公共APIサービスと発行ポータルの一覧
DART電子公示APIキーの取得（即時発行）
国家法令情報センターOC識別子の申請（1–2営業日）
KOSIS国家統計ポータルAPIキーの申請
.envへの環境変数設定（Windows / macOS / Linux）
curlによる動作確認とトラブルシューティング

1. 概要

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

流れは3サービスとも同じです。スキルが環境変数を読み → curlリクエストにキーを載せて送信 → JSONレスポンスが返る。一度設定すれば、以降のすべてのセッションで再利用できます。

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

2. APIキー一覧

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

サービス	提供機関	発行ポータル	承認	環境変数
DART電子公示	韓国金融監督院（FSS）	opendart.fss.or.kr	即時	`DART_API_KEY`
国家法令情報センター	韓国法制処（MOLEG）	open.law.go.kr	1–2営業日	`LAW_API_OC`
KOSIS国家統計ポータル	韓国統計庁（KOSTAT）	kosis.kr/openapi	ポータル掲示板で確認	`KOSIS_API_KEY`

法令ポータルはキー文字列を発行せず、登録時に使用したメールIDをOC識別子として使います。KOSISの承認手続きと所要時間は公式には文書化されていません。申請後はポータルの掲示板で確認してください。

3. DART電子公示API

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

取得方法

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

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

リクエスト方法

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

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

ステータスコード	意味
`000`	正常処理
`010`	未登録のキー
`011`	使用できないキー
`013`	該当データなし
`020`	1日のリクエスト上限超過
`100`	フィールド値のエラー
`800`	システムメンテナンス中

照会できる内容

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

動作確認の例としてよく使われるサムスン電子の corp_code は 00126380 です。キー発行直後にこの値で企業概況を照会してみてください（動作確認セクション参照）。

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

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

申請方法

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

OC識別子

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

リクエストに type=JSON を指定しないと、APIはJSONではなくHTMLページを返します。リクエストごとに必ず type=JSON を含めてください。

照会できる内容

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

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

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

申請方法

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

KOSISの利用申請の承認手続きと所要時間は公式には文書化されていません。申請後、ポータルの掲示板とマイページで承認状態を直接確認してください。承認前はAPI呼び出しが拒否されます。

リクエスト方法

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

照会できる内容

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

6. 環境変数の設定

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

cp .env.sample .env

# country-scoped:KR ブロック — 3つのキーを実際の値に置き換えます
DART_API_KEY=発行された-40文字-の認証キー
LAW_API_OC=登録-メールID@example.com
KOSIS_API_KEY=発行された-KOSIS-キー

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

$env:DART_API_KEY="発行された-40文字-の認証キー"
$env:LAW_API_OC="登録-メールID@example.com"
$env:KOSIS_API_KEY="発行された-KOSIS-キー"

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

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

export DART_API_KEY="発行された-40文字-の認証キー"
export LAW_API_OC="登録-メールID@example.com"
export KOSIS_API_KEY="発行された-KOSIS-キー"

.env ファイルと実際のキーを絶対にGitにコミットしないでください。.env は .gitignore で除外しておく必要があります。キーが漏えた場合は、各ポータルで再発行してください。

7. 動作確認

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

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配列が出力されます。

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

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

症状	サービス	原因と対処
`status` 010 / 011	DART	未登録または使用不可のキー — 認証キーを再確認し、再発行します
`status` 020	DART	1日のリクエスト上限超過 — 翌日に再試行します
`status` 013	DART	該当データなし — 照会期間と `corp_code` を確認します
`totalCnt` 0	法令	一致する法令なし — キーワードを広げ、`target` 値を確認します
JSONの代わりにHTMLが返る	法令	`type=JSON` の指定漏れ — リクエストに `type=JSON` を追加します
承認前に呼び出し失敗	法令 · KOSIS	利用申請の承認前は呼び出せません — 承認完了まで待ちます
`{"err":"21"}`	KOSIS	無効なパラメータ — `objL1`・`itmId` などのコードを統計リスト照会で確認します
`{"err":"30"}`	KOSIS	データなし — キーワードと統計表コードを確認します
Git Bashでハングル文字化け	KOSIS	Windows Git Bashのエンコーディング問題 — ハングル値をパーセントエンコードして直接渡します

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

3サービスが提供するデータはすべて、韓国の公共データ著作物利用許諾 コングヌリ（공공누리、KOGL）ライセンスで提供されます。レポートやエージェントの成果物にデータを引用・再構成する場合は、出典（例: 出典: 韓国金融監督院 DART電子公示）を明記する必要があります。著作物タイプ別の表記方法はコングヌリ公式サイトで確認してください。

← 付録C

低コストAIバックエンド統合