# Korea Trade Statistics API - Import Export by HS Code 수출입실적 (`elabstudio/korea-trade-statistics`) Actor

South Korea monthly import and export statistics by HS code and partner country from official Korea Customs Service data (관세청 수출입무역통계): USD value, kg weight, trade balance, English fields.

- **URL**: https://apify.com/elabstudio/korea-trade-statistics.md
- **Developed by:** [E:LAB STUDIO](https://apify.com/elabstudio) (community)
- **Categories:** Business, Developer tools
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 trade rows

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Korea Trade Statistics API: Import & Export by HS Code (수출입실적)

Get **official South Korean import and export statistics by HS code and partner country** as clean JSON / CSV / Excel. Every row is a monthly figure from the Korea Customs Service (관세청) trade statistics: export value in USD, import value in USD, weight in kg and trade balance, for any product from 2-digit HS chapters down to 10-digit Korean HSK lines.

Ask for `8542` (integrated circuits) with `US` and `CN` and get the monthly breakdown by 6-digit sub-heading for each country. Field names are in English, with the official Korean product description and country name kept next to them. No Korean, no data.go.kr account and no API key needed.

### What you can use it for

- **Market research and sizing**: how much of a product Korea exports to or imports from a country, month by month.
- **Supply chain and sourcing**: find which HS lines Korea buys from China, Vietnam or the US, and how the volume changes.
- **Investment and macro research**: track semiconductors, batteries, cars, ships or cosmetics exports, the indicators analysts watch first.
- **Trade compliance and tariff work**: HS-level values and weights for a specific partner, ready for spreadsheets or BI tools.
- **Data pipelines and AI agents**: a consistent English schema you can schedule monthly.

### Input

| Field | Example | Notes |
|---|---|---|
| `hsCodes` | `["8542", "8703"]` | 2, 4, 6 or 10 digits. Results come one level deeper: 2 -> 4-digit headings, 4 -> 6-digit sub-headings, 6 -> 10-digit HSK lines, 10 -> that line. Empty = all products (then give a country). |
| `products` | `["semiconductors", "cosmetics"]` | Optional plain-English names mapped to HS codes (list below). |
| `countries` | `["US", "Vietnam"]` | ISO 2-letter codes or English names. Empty = all partner countries. |
| `startMonth` / `endMonth` | `2025-01` / `2025-12` | Empty = the latest 12 published months. Longer ranges are split into 12-month requests automatically. |
| `includeTotals` | `true` | Adds one `row_type: "total"` row per request with summed values for the period. |
| `onlyNonZero` | `true` | Skips detail rows where export and import are both 0. |
| `maxItems` | `10000` | Stop after N rows. `0` = no limit. |

Example: Korean chip trade with the US and China over the last year

```json
{ "hsCodes": ["8542"], "countries": ["US", "CN"] }
```

Example: Korean cosmetics exports to every country in 2025

```json
{ "hsCodes": ["3304"], "startMonth": "2025-01", "endMonth": "2025-12" }
```

Example: everything Korea traded with Vietnam in one month, at 10-digit detail

```json
{ "countries": ["VN"], "startMonth": "2026-06", "endMonth": "2026-06", "maxItems": 0 }
```

Product names accepted in `products`: semiconductors, chips, memory chips, processors, cars, auto parts, electric vehicles, batteries, lithium-ion batteries, smartphones, displays, ships, steel, crude oil, petroleum products, lng, cosmetics, skincare, ramen, kimchi, soju, beer, beef, pork, coffee, wine, seaweed, ginseng, tires, plastics, pharmaceuticals, vaccines, computers, solar panels, machinery, medical devices, toys, apparel, furniture.

### Output example

```json
{
  "row_type": "detail",
  "month": "2025-10",
  "query_hs_code": "8542",
  "query_country": "US",
  "hs_code": "854231",
  "hs_digits": 6,
  "hs_chapter": "85",
  "hs_chapter_name_en": "Electrical machinery, electronics, semiconductors",
  "product_name_ko": "프로세서와 컨트롤러[메모리ㆍ변환기ㆍ논리회로ㆍ증폭기ㆍ클록(clock)ㆍ타이밍(timing) 회로나 그 밖의 회로를 갖춘 것인지는 상관없다]",
  "country_code": "US",
  "country_name_en": "United States",
  "country_name_ko": "미국",
  "export_value_usd": 43322718,
  "export_weight_kg": 15746,
  "import_value_usd": 108979795,
  "import_weight_kg": 11427,
  "trade_balance_usd": -65657077,
  "source": "Korea Customs Service (관세청) trade statistics via data.go.kr, license: 이용허락범위 제한 없음"
}
```

Total row for the same request (October 2025 to September 2026): exports $2,844,551,167, imports $2,066,607,242, balance $777,943,925.

### Pricing

Pay per result:

- **$1.50 per 1,000 rows** (detail or total rows)

A year of one 4-digit HS code with one country is typically 20 to 120 rows, so a few cents. You can set a maximum cost per run in Apify and the actor stops when it is reached.

### FAQ

**How fresh is the data?** Korea Customs publishes monthly figures with a delay of about one to two months. By default the actor asks for the 12 months ending two months ago; set `endMonth` to try a more recent month.

**What is the difference between HS and HSK?** The first 6 digits are the international Harmonized System. Korea adds 4 more digits (HSK) for national detail, so 10-digit codes are Korea-specific.

**Is "export" from Korea's point of view?** Yes. `export_value_usd` is what Korea shipped to the partner country and `import_value_usd` is what Korea bought from it. Values are in US dollars, weights in kilograms.

**Can I get English product names?** The official descriptions are Korean only. Each row carries the English HS chapter name, and the HS code itself is international, so you can join it to any English HS nomenclature.

**How far back can I go?** Several years of monthly history are available. Ranges longer than 12 months are split into yearly requests automatically.

**Why is my request rejected?** Give at least one HS code or one country. Without either the request would be every product with every country.

### Source and license

- Korea Customs Service (관세청): 품목별 국가별 수출입실적(GW), via the Public Data Portal (공공데이터포털, data.go.kr, https://www.data.go.kr/data/15100475/openapi.do). License: 이용허락범위 제한 없음 (no restriction on use).

Every result carries a `source` field naming the origin. This actor is not affiliated with the Korean government.

# Actor input Schema

## `hsCodes` (type: `array`):

HS codes with 2, 4, 6 or 10 digits, e.g. 8542 (integrated circuits), 8703 (cars), 3304 (cosmetics). Results come one level deeper: 2 digits -> 4-digit headings, 4 -> 6-digit, 6 -> 10-digit Korean HSK lines. Leave empty for all products (then give a country).

## `products` (type: `array`):

Common product names mapped to HS codes, e.g. semiconductors, cars, batteries, cosmetics, ramen, soju, steel, crude oil. See README for the list.

## `countries` (type: `array`):

ISO 2-letter codes (US, CN, JP, VN) or English names (United States, Vietnam). Leave empty for all partner countries.

## `startMonth` (type: `string`):

YYYY-MM. Empty = 12 months before end month.

## `endMonth` (type: `string`):

YYYY-MM. Empty = two months ago (latest published month). Longer ranges are split into 12-month requests automatically.

## `includeTotals` (type: `boolean`):

Adds one row_type=total row per request with the summed export/import values for the whole period.

## `onlyNonZero` (type: `boolean`):

Drop detail rows where both export and import value are 0.

## `maxItems` (type: `integer`):

Stop after this many rows. 0 = no limit.

## Actor input object example

```json
{
  "hsCodes": [
    "8542"
  ],
  "products": [],
  "countries": [
    "US",
    "CN"
  ],
  "includeTotals": true,
  "onlyNonZero": true,
  "maxItems": 10000
}
```

# Actor output Schema

## `rows` (type: `string`):

Export/import by month, HS code and country.

## `summary` (type: `string`):

Query and row counts.

# 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 = {
    "hsCodes": [
        "8542"
    ],
    "countries": [
        "US",
        "CN"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("elabstudio/korea-trade-statistics").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 = {
    "hsCodes": ["8542"],
    "countries": [
        "US",
        "CN",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("elabstudio/korea-trade-statistics").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 '{
  "hsCodes": [
    "8542"
  ],
  "countries": [
    "US",
    "CN"
  ]
}' |
apify call elabstudio/korea-trade-statistics --silent --output-dataset

```

## MCP server setup

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

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/RfSq3ddxnFhdkE7Il/builds/2yZ8gGRaexSRa5gel/openapi.json