# Korea Customs Trade Data — Exports & Imports by HS Code (`kdata-tools/korea-customs-trade`) Actor

Official Korea Customs Service trade statistics: monthly export and import value (USD) and weight by HS code (2/4/6/10-digit) and partner country, with year-over-year growth. Track Korean semiconductor, battery, auto and K-beauty exports.

- **URL**: https://apify.com/kdata-tools/korea-customs-trade.md
- **Developed by:** [K-Data Tools](https://apify.com/kdata-tools) (community)
- **Categories:** E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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 Customs Trade Data: Monthly Exports/Imports by HS Code & Country (Official KCS)

Official **Korea Customs Service (KCS)** trade statistics. You get monthly **export and import value (USD) and weight (kg)** for any **HS code** (2, 4, 6 or 10 digits) and **partner country**, with **year-over-year growth** calculated for you.

Korea's trade numbers are a leading indicator for the global chip, battery, auto and consumer-goods cycles. Use this Actor to track them straight from the official source, with no Korean-language portal and no spreadsheets.

### Use cases

- **Semiconductor and tech analysts**: Korean exports of HS 8542 (integrated circuits), for example memory, going to China, Taiwan, Vietnam and the US
- **Macro and equity research**: monthly trade trends and year-over-year momentum by product and destination
- **Supply-chain and sourcing**: import volumes and unit values from specific countries
- **K-beauty, food and consumer brands**: export trends for HS 3304 (cosmetics), ramen (1902), and more
- **AI agents**: structured English JSON through the Apify API or MCP

### Input

```json
{
  "countries": ["US", "CN", "VN"],
  "hsCodes": ["8542", "850760"],
  "fromMonth": "2025-01",
  "toMonth": "2025-08",
  "includeYoY": true
}
```

- `countries`: 2-letter ISO codes of Korea's partner countries
- `hsCodes`: 2, 4, 6 or 10-digit HS codes. Popular codes:
  - 8542: integrated circuits
  - 850760: lithium-ion batteries
  - 8703: passenger cars
  - 3304: cosmetics
  - 8517: phones and telecom equipment
  - 2710: refined petroleum
  - 8901: ships
- Long ranges are split into 12-month requests automatically.

### Output (one record per month × country × HS code)

```json
{
  "period": "2025-08",
  "countryCode": "US",
  "countryNameEn": "United States",
  "countryNameKo": "미국",
  "hsCode": "8542",
  "productNameKo": "전자집적회로",
  "exportUsd": 0,
  "importUsd": 0,
  "tradeBalanceUsd": 0,
  "exportKg": 0,
  "importKg": 0,
  "exportYoY": 0.0,
  "importYoY": 0.0
}
```

`exportYoY` of `0.25` means +25% versus the same month one year earlier. It is `null` when there is no prior-year value.

### Pricing

Pay per event: **$2 per 1,000 monthly trade records** ($0.002 each), plus Apify's standard $0.00005 run-start fee.

| Example | Records | Cost |
|---|---|---|
| Chips (HS 8542) to US + China, 8 months, totals + 5 sub-codes | 96 | $0.19 |
| Total trade (all goods) with 12 countries, 12 months | 144 | $0.29 |
| One HS code × one country × 12 months, totals only | 12 | $0.024 |
| "No data" rows | – | Free |

The one extra prior year fetched for YoY growth is not charged. You can set a maximum cost per run in Apify.

### Data source

- Source: 관세청 품목별 국가별 수출입실적 (Korea Customs Service trade statistics by HS code and country), data.go.kr dataset 15100475. The dataset is licensed for use without restriction (이용허락범위 제한 없음).
- Values are in USD and weights in kg, as published by KCS. Recent months may be revised in later releases.
- Some partner codes are customs-specific (e.g. `ZZ` for unspecified or other destinations). These have `countryNameEn: null` and keep the Korean name.
- This Actor runs in your own Apify account. Its developer does not keep copies of your inputs or results.
- The data is provided as is. This Actor is not affiliated with or endorsed by the Korea Customs Service.

# Actor input Schema

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

2-letter ISO country codes of Korea's trade partners, e.g. US, CN, VN, JP, TW, DE.

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

Harmonized System codes, 2/4/6 digits (10-digit also accepted). Leave empty for total trade with each country (all goods). Examples: 8542 (integrated circuits / semiconductors), 850760 (lithium-ion batteries), 8703 (passenger cars), 3304 (cosmetics / K-beauty).

## `fromMonth` (type: `string`):

YYYY-MM. Default: January of the To-month's year.

## `toMonth` (type: `string`):

YYYY-MM. Default: last month.

## `includeYoY` (type: `boolean`):

Adds exportYoY / importYoY (e.g. 0.25 = +25%) versus the same month one year earlier.

## `outputLevel` (type: `string`):

total = one row per month for each requested HS code (e.g. all of 8542). detail = the sub-codes one level below (8542 -> 854231 processors, 854232 memory...). Without HS codes, only country totals (all goods) are returned.

## Actor input object example

```json
{
  "countries": [
    "US",
    "CN"
  ],
  "hsCodes": [
    "8542"
  ],
  "includeYoY": true,
  "outputLevel": "both"
}
```

# Actor output Schema

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

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

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

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,kdata-tools/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/CTR0aaATvOOz5sH1t/builds/GC35cRHlBMwNOOR51/openapi.json