별첨 D

한국 오픈데이터 API 키 발급과 설정 (DART · ECOS · KRX · KOSIS · 법제처 · 공공데이터포털)

이 별첨에서는 국가 스코프로 제공되는 k-* 스킬이 사용하는 한국 공공 오픈데이터 API — 금융감독원 DART 전자공시, 한국은행 경제통계시스템(ECOS), 한국거래소(KRX) 데이터 마켓플레이스, 법제처 국가법령정보센터, 통계청 KOSIS 국가통계포털, 공공데이터포털(data.go.kr) — 의 키를 발급받고 환경 변수로 설정하는 방법을 설명합니다.

이 별첨에서 다루는 것

공공 API 서비스와 발급 포털 한눈에 보기
DART 전자공시 API 키 발급 (즉시 발급)
ECOS 인증키 발급과 공개 데모 키 활용
KRX 데이터 마켓플레이스 관리자 승인 절차
국가법령정보센터 OC 식별자 신청 (1–2 영업일)
KOSIS 국가통계포털 API 키 신청
공공데이터포털(data.go.kr) 서비스키 발급과 데이터셋별 활용신청
.env 환경 변수 설정 (Windows / macOS / Linux)
curl 동작 확인과 문제 해결

개요

이 작업 공간에는 한국 공공 데이터를 조회하는 국가 스코프(KR) 스킬 여섯 개가 포함되어 있습니다. k-dart는 금융감독원 전자공시(DART), k-ecos는 한국은행 ECOS 거시·금융 통계, k-krx는 KRX 거래소 시세 데이터, k-law는 법제처 국가법령정보센터, k-kosis는 통계청 KOSIS 국가통계포털, k-opendata는 공공데이터포털(data.go.kr)의 Open API를 호출합니다. 모든 k-* 스킬은 요청 직전에 환경 변수에서 키를 읽으므로, 스킬을 쓰기 전에 각 서비스의 키를 발급받아 설정해 두어야 합니다.

흐름은 모든 k-* 서비스에서 동일합니다: 스킬이 환경 변수를 읽고 → curl 요청에 키를 실어 보내면 → JSON 응답이 돌아옵니다. 키는 한 번만 설정하면 이후 모든 세션에서 재사용됩니다.

여섯 서비스 모두 무료로 제공되며 개인 개발자도 발급 절차만 거치면 바로 사용할 수 있습니다. 다만 승인 소요 시간은 서비스마다 다릅니다 — DART와 ECOS는 즉시 발급되고, 국가법령정보센터는 1–2 영업일이 걸리며, KRX와 공공데이터포털 일부 데이터셋은 관리자 승인이 필요하고, KOSIS는 공식 문서화된 기준이 없어 포털 공지로 확인해야 합니다.

API 키 한눈에 보기

발급 대상 서비스를 표로 정리합니다. 상세 발급 절차는 각 서비스 섹션을 참조하세요.

서비스	제공 기관	발급 포털	승인 소요	환경 변수
DART 전자공시	금융감독원 (FSS)	opendart.fss.or.kr	즉시	`DART_API_KEY`
ECOS 경제통계시스템	한국은행 (BOK)	ecos.bok.or.kr	즉시; 공개 데모 키 `sample`로 10행 이하 조회 가능	`ECOS_API_KEY`
KRX 데이터 마켓플레이스	한국거래소 (KRX)	openapi.krx.co.kr	관리자 승인 + 서비스별 활용신청; 데모 키 없음	`KRX_API_KEY`
국가법령정보센터	법제처 (MOLEG)	open.law.go.kr	1–2 영업일	`LAW_API_OC`
KOSIS 국가통계포털	통계청 (KOSTAT)	kosis.kr/openapi	포털 공지 확인	`KOSIS_API_KEY`
공공데이터포털 (관세청 수출입무역통계)	행정안전부 / 관세청	data.go.kr	포털 서비스키는 즉시; 개별 데이터셋 활용신청은 기관별 상이	`DATA_GO_KR_API_KEY`

국가법령정보센터는 별도의 키 문자열 대신 가입 시 등록한 이메일 ID를 OC 식별자로 사용합니다. KOSIS의 승인 절차와 소요 시간은 공식적으로 문서화되어 있지 않으니, 신청 후 포털 공지사항에서 확인하세요.

DART 전자공시 API

DART는 금융감독원이 운영하는 전자공시시스템의 Open API입니다. 상장회사 공시 목록부터 기업 개황, 재무제표, 주요사항보고까지 기계가 읽기 쉬운 형태로 제공하므로, 기업 분석 에이전트의 데이터 원천으로 활용할 수 있습니다.

발급 방법

opendart.fss.or.kr 회원가입 페이지 에서 계정을 만듭니다.
로그인 후 인증키 신청 메뉴에서 Open API 인증키를 발급받습니다.
발급된 키(40자리 문자열)를 안전한 곳에 보관합니다 — 마이페이지에서 다시 확인할 수 있습니다.

인증키는 즉시 발급되며 별도 승인 대기가 없습니다.

요청 방식

키 전달 — 모든 요청에 crtfc_key 파라미터로 40자리 인증키를 전달합니다.
일일 한도 — 하루 약 20,000건까지 요청할 수 있습니다. 초과하면 상태 코드 020이 반환됩니다.
고유번호 필수 — 기업별 엔드포인트 대부분은 8자리 corp_code를 요구합니다. corpCode.xml(고유번호 파일)을 내려받아 회사명으로 검색해 확인합니다.

주요 상태 코드는 다음과 같습니다.

상태 코드	의미
`000`	정상 처리
`010`	등록되지 않은 키
`011`	사용할 수 없는 키
`013`	조회된 데이터가 없음
`020`	일일 요청 한도 초과
`100`	필드 값 오류
`800`	시스템 점검 중

조회할 수 있는 것

공시검색 — 날짜·회사·보고서 종류별 공시 목록
기업개황 — 회사 개요, 업종, 자본금 등 기본 정보
재무제표 — 단일·복수 회사 주요계정 및 전체 재무제표
주요사항보고 — 무상주식발행, 자본변동 등 주요 보고 항목

동작 확인 예제로 자주 쓰이는 삼성전자의 corp_code는 00126380입니다. 키 발급 직후 이 값으로 기업개황을 조회해 보세요 (동작 확인 섹션 참조).

ECOS 경제통계시스템 API

k-ecos는 한국은행 경제통계시스템(ECOS)을 조회합니다. 기준금리, 환율, 통화량, GDP, 100대 통계지표 빠른 조회까지 한국 거시·금융 통계의 1차 출처입니다.

발급 방법

가입 없이 바로 시험할 수 있습니다 — 공개 데모 키(문자 그대로 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).

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으로 돌아옵니다 — 디버깅할 때는 두 필드를 그대로 확인하세요.

국가법령정보센터 API

국가법령정보센터는 법제처가 운영하는 법령 통합 포털입니다. 현행 법령 본문은 물론 판례·행정규칙·자치법규까지 Open API로 제공하므로, 법령 검색·요약 스킬의 데이터 원천으로 사용합니다.

신청 방법

open.law.go.kr 에서 회원가입한 뒤, 상단 메뉴 OPEN API > 활용신청에서 사용할 API를 선택해 신청합니다. 승인까지 보통 1–2 영업일이 걸립니다.

OC 식별자

국가법령정보센터 API는 별도의 키 문자열을 발급하지 않습니다. 대신 가입할 때 등록한 이메일 ID 전체(예: myname@example.com)를 OC 식별자로 사용합니다. 환경 변수 LAW_API_OC에 이메일 ID를 그대로 저장하고, 요청 시 OC= 파라미터로 전달합니다.

요청에 type=JSON을 명시하지 않으면 API는 JSON 대신 HTML 페이지를 반환합니다. 요청마다 반드시 type=JSON을 포함하세요.

조회할 수 있는 것

현행법령 — 법률·시행령·시행규칙 본문과 조회
판례 검색 — 대법원·헌법재판소 결정례
행정규칙·자치법규 — 훈령·예규, 조례·규칙
법령해석례·조약 — 유권해석 사례와 국제 조약 정보

KOSIS 국가통계포털 API

KOSIS는 통계청이 운영하는 국가통계포털입니다. 인구·경제·사회 전반의 공식 통계표를 Open API로 제공하므로, 통계 조회·시계열 분석 스킬의 데이터 원천으로 사용합니다.

신청 방법

kosis.kr/openapi 에서 회원가입한 뒤 활용신청 메뉴에서 Open API 사용을 신청합니다.

KOSIS의 활용신청 승인 절차와 소요 시간은 공식적으로 문서화되어 있지 않습니다. 신청 후 포털 공지사항과 마이페이지에서 승인 상태를 직접 확인하세요. 승인 전에는 API 호출이 거부됩니다.

요청 방식

키 전달 — 환경 변수 KOSIS_API_KEY에 키를 저장하고, 요청 시 apiKey= 파라미터로 전달합니다.
오류 응답 — 파라미터 오류는 {"err":"21"}, 조회 결과 없음은 {"err":"30"} 형태로 반환됩니다.
코드 확인 — 통계표 코드는 objL1, 항목 코드는 itmId처럼 요청마다 필요하며, 통계목록 조회를 단계적으로 따라가며 확인합니다.

조회할 수 있는 것

통합검색 — 통계표·항목 키워드 검색
통계목록 — 분류별 통계표 목록
통계자료 — 실제 수치 데이터
통계설명 — 통계표의 정의·단위·주석

공공데이터포털 (data.go.kr) API

k-opendata는 공공데이터포털(data.go.kr)을 조회합니다. 이 포털은 수십 개 정부 기관의 Open API를 하나의 계정·서비스키 체계로 묶어 제공하는 공용 게이트웨이입니다. 포털 서비스키 하나로 게시된 모든 데이터셋의 인증을 통과하지만, 각 데이터셋(기관 + API)마다 별도의 활용신청을 거쳐야 실제 호출이 허용됩니다. 이 핸드북은 그중 관세청(수출입무역통계) API를 대표 예시로 다룹니다 — HS 코드 단위의 수출입 실적처럼 KOSIS에서는 조회할 수 없는 무역 통계가 필요할 때 사용합니다.

발급 방법

data.go.kr 에서 회원가입하고 일반 인증키(Encoding/Decoding)를 발급받습니다 — 승인 없이 즉시 발급됩니다.
이 서비스키는 포털 전체에서 재사용되지만, 실제로 호출하려는 개별 데이터셋마다 상세 페이지에서 별도로 활용신청을 제출해야 합니다.
데이터셋별 승인 소요 시간은 기관마다 다르므로, 마이페이지의 개발계정/운영계정 상태에서 승인 여부를 확인합니다.

발급받은 서비스키는 DATA_GO_KR_API_KEY 환경 변수에 저장합니다.

조회할 수 있는 것 (관세청 수출입무역통계)

품목별 국가별 수출입실적 — HS 코드 단위로 국가·기간별 수출입 금액·중량을 조회
전체/지역별 수출입 총계 — 국가 전체 또는 시도 단위의 무역수지 동향

관세청 API의 strtYymm/endYymm 조회 기간은 요청당 1년 이내로 제한됩니다. 그보다 긴 기간을 조회하려면 연도별로 반복 호출해야 합니다.

환경 변수 설정

발급받은 키는 프로젝트 루트의 .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="발급받은-공공데이터포털-서비스키"

.env 파일과 실제 키를 절대 Git에 커밋하지 마세요. .env는 .gitignore로 제외되어 있어야 하며, 키가 노출되었다면 각 포털에서 재발급하세요.

동작 확인

키가 올바르게 설정되었는지 간단한 curl 호출로 확인합니다. 명령마다 환경 변수를 읽어 요청을 보내므로, 설정 직후 같은 터미널에서 실행하세요.

ECOS — 100대 통계지표 (공개 sample 키로 동작, 가입 불필요)

# ECOS — 100대 통계지표 (공개 데모 키로 동작)
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 배열이 출력됩니다.

문제 해결

자주 발생하는 증상과 조치 방법을 정리합니다.

증상	서비스	원인과 조치
`status` 010 / 011	DART	등록되지 않았거나 사용 불가한 키 — 인증키를 다시 확인하고 재발급합니다
`status` 020	DART	일일 요청 한도 초과 — 다음 날 재시도합니다
`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 인코딩 문제 — 한글 값을 퍼센트 인코딩해 직접 전달합니다

라이선스와 출처 표기

DART · 법제처 · KOSIS · 공공데이터포털 네 공공 서비스가 제공하는 데이터는 모두 공공누리(KOGL) — 한국 공공데이터 저작물 이용허락 — 라이선스로 제공됩니다. ECOS와 KRX API는 각자의 이용약관(경제통계 Open API 이용약관 / KRX 데이터 마켓플레이스 이용약관)을 따릅니다. 보고서나 에이전트 결과물에 데이터를 인용·재구성할 때는 출처(예: 출처: 금융감독원 전자공시 DART)를 표기해야 합니다. 저작물 유형별 표기 방식은 공공누리 누리집에서 확인하세요.