Korea Customs Trade Statistics

Fetch South Korea's official export and import trade statistics via the UN Comtrade public API. No API key or registration required. Filter by HS code, country, trade direction, and date range. Outputs structured records with trade amount (USD) and weight per month or year.

---

Use Cases

• Track which goods Korea exports to or imports from specific countries
• Monitor trade trends in electronics (HS 85), semiconductors (HS 8542), chemicals (HS 29), or any HS chapter
• Compute Korea's trade balance by commodity or partner country
• Feed macro data into trading signals or economic research

---

No Setup Required

This Actor uses the UN Comtrade public preview API — completely free, no registration, no API key. Just configure your filters and run.

Data source: UN Comtrade — the world's largest repository of international merchandise trade statistics, sourced directly from Korea Customs Service (reporter code 410).

---

Input Parameters

Parameter	Type	Required	Default	Description
trade_type	enum	—	both	export / import / both
stat_mode	enum	—	monthly	monthly (YYYYMM) or annual (YYYY) granularity
start_period	string	—	3 months ago	Start period: YYYYMM for monthly, YYYY for annual
end_period	string	—	Current month	End period: YYYYMM for monthly, YYYY for annual
hs_code	string	—	—	HS chapter filter (2-digit, e.g. 85 for electrical machinery). Leave empty for total.
country_code	string	—	—	ISO 3166-1 alpha-2 partner country code (e.g. US, CN, JP). Leave empty for world total.
max_results	integer	—	500	Cap on total records returned

Common HS code examples:

• 85 — Electrical machinery & electronics
• 8542 — Semiconductors / integrated circuits
• 87 — Vehicles & automotive parts
• 27 — Mineral fuels (oil, LNG)
• 29 — Organic chemicals

Data lag note: UN Comtrade monthly data typically lags ~6 months; annual data lags ~18 months. For very recent months, use Korea Customs' official portal at tradedata.go.kr.

---

Output Schema

Each record in the dataset has the following fields:

{
  "period": "202401",
  "hs_code": "85",
  "hs_code_name": null,
  "country_code": "WLD",
  "country_name": null,
  "trade_type": "export",
  "amount_usd": 54645301472.0,
  "weight_kg": null,
  "quantity": null,
  "freq": "monthly",
  "ref_year": 2024,
  "ref_month": 1
}

Field	Type	Description
period	string	YYYYMM (monthly) or YYYY (annual)
hs_code	string	HS commodity code (or TOTAL)
hs_code_name	string	Commodity description
country_code	string	Trading partner ISO alpha-2 code (or WLD for world)
country_name	string	Trading partner name
trade_type	string	export or import
amount_usd	number	Trade value in USD (FOB for exports, CIF for imports)
weight_kg	number	Net weight in kilograms
freq	string	monthly or annual
ref_year	integer	Reference year
ref_month	integer	Reference month (monthly only)

---

Example Inputs

Korea total exports by month (last 3 months):

{
  "trade_type": "export",
  "stat_mode": "monthly"
}

Electronics (HS 85) exports to USA for 2023:

{
  "trade_type": "export",
  "stat_mode": "annual",
  "start_period": "2023",
  "end_period": "2023",
  "hs_code": "85",
  "country_code": "US"
}

All trade with China for 2022–2023:

{
  "trade_type": "both",
  "stat_mode": "annual",
  "start_period": "2022",
  "end_period": "2023",
  "country_code": "CN"
}

---

Pricing (Pay-Per-Event)

Event	Price
Actor start	$0.001 (flat)
Per trade record returned	$0.002

A typical run fetching 3 months of monthly data (~6 records) costs approximately $0.01.

---

Error Handling

• Each API request is retried up to 3 times with exponential back-off on transient failures
• Rate limiting (HTTP 429) is handled with automatic back-off
• max_results is enforced strictly — stops as soon as the cap is reached

---

Notes

• No API key required — uses the UN Comtrade public preview endpoint
• Export values are FOB (Free on Board); import values are CIF (Cost, Insurance, Freight)
• The preview API returns aggregate data; per-HS-code breakdowns require a full Comtrade subscription
• Source: UN Comtrade (data sourced from Republic of Korea, reporter code 410)

Keywords: South Korea trade, exports, imports, UN Comtrade, Korea customs, HS code, trade statistics, Korean economy, trade balance