k-opendata
Queries Korea's Public Data Portal (`공공데이터포털`, data.go.kr) Open API — a shared gateway hosting Open APIs from dozens of Korean government agencies under one account/service-key system. Documents the portal's common activation flow (활용신청 → 개발/운영계정 → 인증키) and the verified Korea Customs Service (`관세청`) trade-statistics endpoints (HS-code-level import/export by country, national/regional totals) as the primary reference API set. Requires DATA_GO_KR_API_KEY environment variable.
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-14
- Stars
- ★ 25
- Forks
- 9
01 前言 Front Matter
- lang
- ko
- name
- k-opendata
- owner
- public-data-analyst
- scope
- common
- status
- active
- version
- 1.2.3
- metadata
- { "type": "domain", "locale": "ko-KR", "source": "https://www.data.go.kr/", "license": "KOGL (`공공누리`)", "category": "trade-statistics", "triggers": [ "k-opendata", "/k-opendata", "공공데이터포털", "data.go.kr", "`관세청`", "`수출입무역통계`", "`품목별 국가별 수출입실적`", "Korea Customs Service trade statistics", "HS code trade data" ] }
- relates_to
- [ { "type": "composes_with", "skill": "k-ecos" }, { "type": "relates_to", "skill": "k-kosis" } ]
- description
- Queries Korea's Public Data Portal (`공공데이터포털`, data.go.kr) Open API — a shared gateway hosting Open APIs from dozens of Korean government agencies under one account/service-key system. Documents the portal's common activation flow (활용신청 → 개발/운영계정 → 인증키) and the verified Korea Customs Service (`관세청`) trade-statistics endpoints (HS-code-level import/export by country, national/regional totals) as the primary reference API set. Requires DATA_GO_KR_API_KEY environment variable.
- lang_reason
- proper-noun
- l2_propagate
- true
- last_reviewed
- 1788393600000
- prerequisites
- DATA_GO_KR_API_KEY environment variable
02 资源文件 1
- 参考文档references/terms-ko.json2.9 KB
03 SKILL.md 正文
Composition note: the Korea-Customs analysis workflows that compose with this skill (
hs-classification-workflow,market-entry-strategy,landed-cost-calculation) live in the co-export variant (templates/co-export/skills/) and are linked there.
Context
Unified skill for Korea's Public Data Portal (공공데이터포털, data.go.kr) — the shared Open API
gateway for Korean government agencies. One portal account and one issued serviceKey work
across every dataset hosted there, but each individual dataset (agency + API) still requires
its own separate 활용신청 (usage request) before that specific endpoint will accept the key.
This skill documents the shared activation mechanics plus the Korea Customs Service (관세청)
trade-statistics family of APIs, which give HS-code-level import/export figures — the exact
gap that k-kosis cannot fill (KOSIS has no public per-HS-code trade table; see k-kosis
Notes). Use this whenever HS-code-specific 수출입 실적/동향 (trade performance/trend) data is
needed for classification, market-entry, or landed-cost work.
When to Use
- HS-code-level import/export value, weight, or trade-balance lookup (national total, by country, or by 시도) — e.g. "HS 841440 수출입 동향 조회"
- Cross-checking a UN Comtrade or KOSIS-proxy trade figure against the authoritative Korean customs-clearance source
- Any other data.go.kr-hosted government dataset the user names explicitly (this skill's activation flow section applies portal-wide, even though the documented endpoints below are customs-specific)
Execution Steps
- Verify Prerequisites: Confirm
DATA_GO_KR_API_KEYenvironment variable is set. If not, guide the user through Portal Activation Flow below — do not attempt to query without a key (SERVICE_KEY_IS_NULL, error code 20). - Select the endpoint: Match the user's need to one of the Korea Customs Service Trade
Statistics APIs below. For a single HS code across countries/time,
품목별 국가별 수출입실적(GW)(nitemtrade) is almost always correct. - Resolve required parameters:
strtYymm/endYymm(YYYYMM, must span ≤ 1 year per request — loop year-by-year for longer ranges, matching the loop pattern used against UN Comtrade earlier in this kind of task) andcntyCd(2-letter country code) are required fornitemtrade; onlyhsSgn(the HS code, up to 10 digits) is optional-but-essential for this use case — always pass it. - Query: Call the endpoint over HTTPS with
serviceKeyURL-encoded (the key contains+,/,=— use--data-urlencode, never raw string interpolation, or the key will be silently mangled). - Parse Response: Default response is XML (unlike KOSIS's JSON). Check the
<resultCode>/<resultMsg>envelope first —00is success; anything else is a documented error (see Failure Modes). Some data.go.kr APIs accept&type=jsonfor a JSON response — ⚠️ unverified for this specific API; try it, and fall back to XML parsing if unsupported. Watch for a trailing aggregate row: live testing (2026-09-03) confirmed that astrtYymm–endYymmrange query returns an extra<item>withyear(orpriodTitle) set to총계(total) summing the whole range, with dimension fields (hsCode/hsCd,statCd,statKor, etc.) set to-. Filter this row out before per-period analysis, or double-counting results; keep it only when a range total is explicitly wanted. - Aggregate if needed:
cntyCdis required per call onnitemtrade— there is no "world total" pseudo-code for that endpoint. For a national total across all countries, use수출입총괄(GW)(getNewtradeList) directly — confirmed below to take no country or HS parameter, i.e. it is the pre-aggregated national total, no loop-and-sum needed. It has no HS-code split, though; if both a national total and an HS-code breakdown are needed, still loopnitemtradeper country and sum. - Format Output: Present figures with unit (USD amount, kg weight) and period, sorted
chronologically; append disclaimer "
공공데이터포털(data.go.kr) 관세청 Open API 자료 기준". - Save to Deliverables: Store research findings in
deliverables/research/per project conventions.
Output Format
- Trade data: HS code / product name / country / period (YYYYMM) / export amount (USD) / export weight (kg) / import amount (USD) / import weight (kg) / trade balance, sorted by period
- Always cite: "
공공데이터포털(data.go.kr) 관세청 Open API 자료 기준"
Reference Material
references/terms-ko.json: Korean-original customs terminology mapping (endpoint names ↔ operations, field aliases incl. thehsCd/hsCodeinconsistency, portal terms, error messages). Non-Markdown reference asset, exempt from the workspace English-only doc policy. A confirmed JSON response shape (&type=jsonsupport) discovered in recurring lookups goes there.
Related Skills
- k-ecos (BOK macro-financial series — complements customs trade figures for balance-of-payments context)
- k-kosis (macro/aggregate statistics — not HS-code-level; use this skill instead for per-HS-code trade figures)
- hs-classification-workflow (HS code must be confirmed before trade-trend lookup is meaningful)
- market-entry-strategy
- landed-cost-calculation
공공데이터포털 (data.go.kr) Open API Specification
Portal Activation Flow
⚠️ Not independently live-tested this session — derived from data.go.kr help documentation
and general-purpose search (fetched 2026-09-03). Confirm exact UI copy/timing against the live
portal, as public-sector portals occasionally reorganize.
- 회원가입/로그인: Create a data.go.kr account (separate system from KOSIS/DART/Law Open API accounts — each Korean government Open API portal has its own account).
- 데이터셋 검색: Search
데이터셋 > 오픈APIfor the target dataset (e.g. "관세청 품목별 국가별 수출입실적"). - 활용신청: Open the dataset's
openapi.dodetail page and click활용신청. Required fields: 인증유형, 활용용도, 활용목적, 상세기능 선택, 표준약관 동의. - 개발계정 vs 운영계정:
- 개발계정 (dev): Immediate/fast approval in most cases; traffic-capped (관세청 APIs: 10,000 calls/day). Sufficient for research/lookup use.
- 운영계정 (production): Requires review — must register a usage case (활용사례) and request a specific traffic quota. Only needed for a deployed, recurring-traffic service.
- 인증키 발급: 마이페이지 → 인증키 확인. One service key per account, shared across every
data.go.kr Open API the account has been approved for — but each individual dataset must
still be separately
활용신청-approved before that key will work against it. - Exception: Some 관세청 datasets (e.g.
수출이행내역) additionally require separate UNI-PASS (unipass.customs.go.kr) membership — check the dataset's detail page for this requirement before assuming the data.go.kr key alone is sufficient.
Korea Customs Service (관세청) Trade Statistics APIs
| API (Korean name) | Granularity | Base URL | Status |
|---|---|---|---|
| 품목별 국가별 수출입실적(GW) | HS code × country × month | https://apis.data.go.kr/1220000/nitemtrade/getNitemtradeList |
✅ Live-tested — see below |
| 품목별 수출입실적(GW) | HS code × month (no country split) | https://apis.data.go.kr/1220000/Itemtrade/getItemtradeList |
✅ Live-tested — see below |
| 국가별 수출입실적(GW) | Country × month (no HS split) | https://apis.data.go.kr/1220000/nationtrade/getNationtradeList |
✅ Live-tested — see below |
| 수출입총괄(GW) | National monthly total | https://apis.data.go.kr/1220000/Newtrade/getNewtradeList |
✅ Live-tested — see below |
| 시도별 수출입실적(GW) | Korean 시/도 × month | https://apis.data.go.kr/1220000/sidotrade/getSidotradeList |
❌ 403 — key not 활용신청-approved for this dataset yet, see below |
| 수출이행내역 | Export fulfillment records | resolve via openapi.do | ⚠️ Requires separate UNI-PASS membership |
1. 품목별 국가별 수출입실적 (getNitemtradeList)
GET https://apis.data.go.kr/1220000/nitemtrade/getNitemtradeList
| Parameter | Required | Description |
|---|---|---|
serviceKey |
Y | Issued authentication key (≤100 chars; URL-encode — contains reserved chars) |
strtYymm |
Y | Start period, YYYYMM (e.g. 202401) — window must be ≤ 1 year |
endYymm |
Y | End period, YYYYMM |
cntyCd |
Y | Country code, 2 characters (e.g. CN, US, JP) |
hsSgn |
N | HS code, up to 10 digits — omit for all HS codes to that country (large response) |
Response format: XML. Fields (body.items.item): year, hsCd (⚠️ not hsCode — differs
from getItemtradeList's field name for the same concept), statCd (country code),
statCdCntnKor1 (country name), statKor (product name), expDlr, expWgt, impDlr, impWgt,
balPayments. The trailing 총계 row (see Execution Step 5) sets hsCd/statCd/statKor/etc.
to -.
✅ Live-tested 2026-09-03 with a real DATA_GO_KR_API_KEY (strtYymm=202401,
endYymm=202403, cntyCd=CN, hsSgn=841440) — resultCode 00, response matched the fields
above exactly.
Example Request (live-tested 2026-09-03)
curl -sS --get 'https://apis.data.go.kr/1220000/nitemtrade/getNitemtradeList' \
--data-urlencode "serviceKey=$DATA_GO_KR_API_KEY" \
--data-urlencode 'strtYymm=202401' \
--data-urlencode 'endYymm=202412' \
--data-urlencode 'cntyCd=CN' \
--data-urlencode 'hsSgn=841440'
⚠️ If DATA_GO_KR_API_KEY in .env/environment is already percent-encoded (contains literal
%2F, %3D sequences), interpolate it raw into the URL instead of --data-urlencode — double-
encoding it (%2F → %252F) breaks the key. Check the raw value before choosing which form to
use.
2. 품목별 수출입실적 (getItemtradeList)
GET https://apis.data.go.kr/1220000/Itemtrade/getItemtradeList
| Parameter | Required | Type | Description |
|---|---|---|---|
serviceKey |
Y | string | Issued authentication key |
strtYymm |
Y | number | Start period, YYYYMM |
endYymm |
Y | number | End period, YYYYMM |
hsSgn |
N | number | HS code — omit for all HS codes (large response) |
Response format: XML. Fields (body.items.item): year, hsCode (⚠️ note: this endpoint
uses hsCode, while nitemtrade uses hsCd for the same concept — do not assume field names
are consistent across sibling endpoints), statKor (product name), expDlr, expWgt, impDlr,
impWgt, balPayments (trade balance). No country split — use nitemtrade instead when a
country breakdown is also needed. Trailing 총계 row sets hsCode/statKor to -.
✅ Live-tested 2026-09-03 with a real key (strtYymm=202401, endYymm=202403,
hsSgn=841440) — resultCode 00, fields matched exactly.
3. 국가별 수출입실적 (getNationtradeList)
GET https://apis.data.go.kr/1220000/nationtrade/getNationtradeList
| Parameter | Required | Type | Description |
|---|---|---|---|
serviceKey |
Y | string | Issued authentication key |
strtYymm |
Y | string | Start period, YYYYMM |
endYymm |
Y | string | End period, YYYYMM |
cntyCd |
N | string | Country code — omit for all countries (large response) |
Response format: XML. Fields (body.items.item): year, statCd (country code),
statCdCntnKor1 (country name), expDlr, expCnt, impDlr, impCnt, balPayments. No HS-code
split — use nitemtrade instead when an HS breakdown is also needed. Note the field naming
inconsistency vs. nitemtrade/Itemtrade: weight here is expCnt/impCnt, not expWgt/impWgt
— confirm the unit (documented portal-wide as net weight, kg) before treating it as a count.
✅ Live-tested 2026-09-03 with a real key (strtYymm=202401, endYymm=202403,
cntyCd=CN) — resultCode 00, fields matched exactly. No 총계 row appeared when cntyCd
was passed for a single country; unconfirmed whether one appears when cntyCd is omitted.
4. 수출입총괄 (getNewtradeList)
GET https://apis.data.go.kr/1220000/Newtrade/getNewtradeList
| Parameter | Required | Type | Description |
|---|---|---|---|
serviceKey |
Y | string | Issued authentication key |
strtYymm |
Y | string | Start period, YYYYMM |
endYymm |
Y | string | End period, YYYYMM |
Response format: XML. Fields (body.items.item): year, expDlr, expCnt, impDlr,
impCnt, balPayments. No country or HS-code parameter at all — this confirms it as the
pre-aggregated national monthly total referenced in Execution Step 6 above; no loop-and-sum
needed for a world-total figure.
✅ Live-tested 2026-09-03 with a real key (strtYymm=202401, endYymm=202403) —
resultCode 00, one <item> per month plus a trailing year="총계" row summing the range.
5. 시도별 수출입실적 (getSidotradeList)
GET https://apis.data.go.kr/1220000/sidotrade/getSidotradeList
| Parameter | Required | Type | Description |
|---|---|---|---|
serviceKey |
Y | string | Issued authentication key |
strtYymm |
Y | number | Start period, YYYYMM |
endYymm |
Y | number | End period, YYYYMM |
sidoCd |
N | string | 시도 code — omit for all 시도 |
Response format: XML. Fields (body.items.item): priodTitle (period), sidoNm (시도 name),
expUsdAmt, expCnt, impUsdAmt, impCnt, cmtrBlncAmt (trade balance).
⚠️ Administrative code change (2026-07-01): 전남광주통합 (Jeonnam-Gwangju merger) and Incheon
지방행정체계 개편 changed sidoCd values. Per the dataset's own notice: queries for periods
on or after 2026-07-01 use code 12 (전남광주통합특별시); queries for periods before
2026-07-01 must use the pre-merger codes 29 (광주광역시) / 46 (전라남도) separately. A
strtYymm/endYymm range spanning the merger date will need two calls with different codes if
scoped to that region — do not assume one sidoCd covers the full range.
✅ Spec confirmed via Swagger explorer, 2026-09-03. ❌ Live-tested 2026-09-03 — failed: the
same key that works for nitemtrade/Itemtrade/nationtrade/Newtrade returned HTTP 403 with
<errMsg>SERVICE_KEY_IS_NOT_REGISTERED_ERROR</errMsg> / returnReasonCode 30 for
sidotrade. This is the per-dataset 활용신청 requirement from the Portal Activation Flow
section made concrete: a portal-wide serviceKey does not automatically work against every
dataset — this specific dataset needs its own separate usage-request approval even though the
sibling 관세청 endpoints above worked immediately. Before using this endpoint, apply for
관세청_시도별 수출입실적(GW) specifically at its openapi.do page and wait for approval.
Retried once a few minutes later with the identical request — same error — so this is a genuine
missing per-dataset approval, not a propagation delay.
Failure Modes
DATA_GO_KR_API_KEYnot set → guide through Portal Activation Flow, then stop- Error code
20(SERVICE_KEY_IS_NULL) → key missing/not passed correctly — check URL-encoding of the key value - Error code
22(traffic quota exceeded) → dev account daily cap (10,000/day for 관세청 APIs) hit; wait for reset or request 운영계정 quota increase - Error code
30(SERVICE_KEY_IS_NOT_REGISTERED_ERROR, HTTP 403,등록되지 않은 서비스키) → the key is valid portal-wide but not yet활용신청-approved for this specific dataset — confirmed live 2026-09-03 againstsidotrade; apply separately on that dataset'sopenapi.dopage, do not assume approval on one 관세청 endpoint covers its siblings strtYymm/endYymmspan > 1 year → split into multiple calls, one per ≤1-year window (loop by year, same pattern as querying UN Comtrade year-by-year)- World-total figure needed → use
수출입총괄(GW)(getNewtradeList) directly (confirmed live 2026-09-03, nocntyCd/hsSgnparameter exists on it); do not loop-and-sumnitemtradeper country unless an HS-code split is also required - Range query returns an unexpected extra row → check for the
총계(total) aggregate row (see Execution Step 5) before treating item count as "one row per period"
Notes
- Data source: 공공데이터포털 (data.go.kr)
- This skill is read-only query only.
- License:
공공누리(KOGL) — cite source when reproducing trade figures in deliverables. - Created 2026-09-03 in
co-exportafter establishing that neither KOSIS nor UN Comtrade give an exact, HS-code-level, 관세청-sourced figure as directly as data.go.kr's customs APIs do; follows thek-kosis/k-dart/k-lawsibling pattern. Not yet promoted totemplates/common/skills/at the workspace root — this project checkout has notemplates/common/directory to propagate into. - 2026-09-03 (continued): all five documented base URLs/operations (
nitemtrade,Itemtrade,nationtrade,Newtrade,sidotrade) confirmed via the portal's own Swagger explorer (활용정보 → 상세기능 → Exploretab on each dataset'sopenapi.dopage — a plain page-text fetch does not surface this tab's content; browser interaction was required). - 2026-09-03 (live test): a real
DATA_GO_KR_API_KEYbecame available and 4 of 5 endpoints (nitemtrade,Itemtrade,nationtrade,Newtrade) were exercised live withresultCode00— confirmed exact field names (including thehsCdvs.hsCodeinconsistency betweennitemtradeandItemtrade) and the trailing총계aggregate-row behavior on range queries.sidotradefailed with error30(key not yet approved for that specific dataset) — see Failure Modes. This is the strongest real-world confirmation of the per-dataset활용신청requirement described in Portal Activation Flow step 5.
04 同仓库更多 Skills
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.