# Korea Card Spending Statistics - 한국 카드 소비 통계 (`gochujang/korea-card-spending`) Actor

Fetches Korea credit/debit card spending statistics from public financial APIs. Covers total spending, industry breakdown, regional patterns, and YoY changes. No scraping — official public data.

- **URL**: https://apify.com/gochujang/korea-card-spending.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 Card Spending Statistics

Fetch official Korean credit and debit card spending statistics from public government APIs — no scraping, no license risk.

**Data source**: Korea Credit Finance Association (여신금융협회) via the Public Data Portal (data.go.kr, service code B552584) and the Financial Supervisory Service statistics system (FISIS, fsis.fss.or.kr). All data is published under the Korean Open Government License (공공누리), permitting free commercial use with attribution.

> **Note**: This Actor does *not* scrape BC Card DataFolio or any private financial portal. Every record comes from officially licensed public APIs.

***

### What You Get

| Field | Description |
|---|---|
| `period` | Year-month string (`YYYYMM`) |
| `stat_type` | Type of statistic returned |
| `industry_code` | Industry code (by\_industry mode) |
| `industry_name` | Industry name in Korean |
| `region_code` | 2-digit region code (by\_region mode) |
| `region_name` | Region name in Korean |
| `approval_count` | Total card approval transactions (integer) |
| `approval_amount_krw` | Total approved amount in KRW (integer) |
| `yoy_change_pct` | Year-over-year change percentage (float, if available) |
| `source` | API source identifier |

***

### Input Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `service_key` | string | Yes | API key from [data.go.kr](https://www.data.go.kr). Free registration, approval in ~1 business day. |
| `stat_type` | select | Yes | `total_monthly`, `by_industry`, `by_region`, or `online_offline` |
| `start_period` | string | Yes | Start year-month in `YYYYMM` format (e.g. `202401`) |
| `end_period` | string | Yes | End year-month in `YYYYMM` format (e.g. `202412`) |
| `industry_code` | string | No | Filter by industry code (only for `by_industry`). See table below. |
| `region_code` | string | No | 2-digit region code (only for `by_region`). E.g. `11` for Seoul. |
| `max_results` | integer | No | Max records per call. Default: 500. |

#### Getting a Free API Key

1. Visit [data.go.kr](https://www.data.go.kr) and create a free account.
2. Search for **"여신금융협회 카드승인통계"** (Korea Credit Finance Association card approval statistics).
3. Click "활용신청" (Request Access). Approval is typically instant or within 1 business day.
4. Copy the `serviceKey` from your My Page and paste it into the Actor input.

***

### Industry Codes (업종 코드)

| Code | Industry |
|---|---|
| `01` | 음식점 (Restaurants) |
| `02` | 유통/쇼핑 (Retail/Shopping) |
| `03` | 여행/교통 (Travel/Transport) |
| `04` | 의료/병원 (Healthcare) |
| `05` | 교육 (Education) |
| `06` | 통신 (Telecom) |
| `07` | 생활서비스 (Daily Services) |
| `08` | 문화/레저 (Culture/Leisure) |
| `09` | 공과금 (Utilities) |
| `10` | 기타 (Other) |

***

### Region Codes (지역 코드)

`11` Seoul · `21` Busan · `22` Daegu · `23` Incheon · `24` Gwangju · `25` Daejeon · `26` Ulsan · `29` Sejong · `31` Gyeonggi · `32` Gangwon · `33` Chungbuk · `34` Chungnam · `35` Jeonbuk · `36` Jeonnam · `37` Gyeongbuk · `38` Gyeongnam · `39` Jeju

***

### API Fallback Behaviour

If the primary data.go.kr API is unavailable or the API key is missing, the Actor automatically attempts the FISIS (금융감독원) endpoint for `total_monthly` queries — no API key required. If both sources fail, the Actor pushes a diagnostic record with `available_alternatives` listing alternative data sources and signup links.

***

### Pricing

| Event | Price |
|---|---|
| Actor start | $0.001 (once) |
| Per spending record returned | $0.001 |

Fetching 12 months of industry data across all sectors typically returns 120–200 records, costing approximately **$0.12–$0.20** per run.

***

### Example Use Cases

- **Macro research**: Track total consumer spending trends by month against interest rate cycles.
- **Sector rotation**: Compare YoY spending growth across industries to identify leading/lagging sectors.
- **Regional analysis**: Map card spending density across Korean provinces for retail site selection.
- **Online vs. offline**: Monitor the structural shift to e-commerce in Korean consumer behaviour.

***

### License

Data is sourced under the [공공누리 제1유형](https://www.kogl.or.kr) (Korea Open Government License Type 1), permitting free use, reproduction, and distribution with attribution.

**Keywords:** South Korea, credit card spending, consumer spending, 여신금융협회, Korea economic data, retail spending, debit card, government statistics

# Actor input Schema

## `mode` (type: `string`):

card\_spending: latest card spending + core consumption indicators. consumption\_all: all consumption-class indicators. timeseries: historical time-series for market context. all: everything combined.

## `ts_indicators` (type: `array`):

Which time-series indicators to include (used when mode=timeseries or all). Options: bok\_base\_rate, deposit\_rate, usd\_krw, kospi.

## `start_date` (type: `string`):

Start date for time-series data. Format: YYYYMMDD for daily, YYYYMM for monthly. Defaults to 90 days ago (daily) or 12 months ago (monthly).

## `end_date` (type: `string`):

End date for time-series data. Same format as start\_date. Defaults to today.

## `service_key` (type: `string`):

Deprecated — no longer needed. This actor now uses BOK ECOS public data without any API key.

## `stat_type` (type: `string`):

Deprecated — use mode instead.

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

Deprecated — use start\_date instead.

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

Deprecated — use end\_date instead.

## Actor input object example

```json
{
  "mode": "card_spending",
  "ts_indicators": [
    "bok_base_rate",
    "usd_krw"
  ]
}
```

# 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-card-spending").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-card-spending").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-card-spending --silent --output-dataset

```

## MCP server setup

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

```

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/izsI1ypwnbxJcjC96/builds/MBKEik5odL72932I3/openapi.json