# Korea Customs Trade Statistics - 관세청 수출입무역통계 (`gochujang/korea-customs-trade`) Actor

Fetches Korea export/import trade statistics from Korea Customs Service. Filter by HS code, country, port, and period. Returns trade amount and weight data.

- **URL**: https://apify.com/gochujang/korea-customs-trade.md
- **Developed by:** [Hojun Lee](https://apify.com/gochujang) (community)
- **Categories:** Business
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-usage

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 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](https://comtradeapi.un.org/) — 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](https://tradedata.go.kr).

***

### Output Schema

Each record in the dataset has the following fields:

```json
{
  "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):**

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

**Electronics (HS 85) exports to USA for 2023:**

```json
{
  "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:**

```json
{
  "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](https://comtradeapi.un.org/) (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

# Actor input Schema

## `trade_type` (type: `string`):

Whether to fetch export, import, or both.

## `stat_mode` (type: `string`):

Monthly returns YYYYMM-granularity data; annual returns YYYY-granularity. Note: UN Comtrade monthly data has ~6 month lag, annual has ~18 month lag.

## `start_period` (type: `string`):

Start period. For monthly: YYYYMM (e.g. 202401). For annual: YYYY (e.g. 2023). Defaults to 3 months ago.

## `end_period` (type: `string`):

End period. For monthly: YYYYMM (e.g. 202406). For annual: YYYY (e.g. 2024). Defaults to current month.

## `hs_code` (type: `string`):

HS commodity code to filter by (2-digit chapter, e.g. '85' for electrical machinery). Leave empty for total trade.

## `country_code` (type: `string`):

ISO 3166-1 alpha-2 country code to filter by (e.g. 'US', 'CN', 'JP'). Leave empty for world total.

## `max_results` (type: `integer`):

Maximum number of trade records to return.

## Actor input object example

```json
{
  "trade_type": "both",
  "stat_mode": "monthly",
  "max_results": 500
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("gochujang/korea-customs-trade").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("gochujang/korea-customs-trade").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call gochujang/korea-customs-trade --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,gochujang/korea-customs-trade"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/dHPrAR7W1U6ZWlHcJ/builds/VHOYYZ9ttWGmOyP3S/openapi.json