# K-Pop Photocard Price Index — Korean Market Medians (`kdatafactory/kpop-photocard-index`) Actor

The first K-pop photocard price index built on Korean-origin market data (Pocamarket). One row per artist/member: listing count, median/min/max USD asking price, average wish count, sample listing URLs. Price against the origin market, not eBay. Aggregated card data only — no seller identity.

- **URL**: https://apify.com/kdatafactory/kpop-photocard-index.md
- **Developed by:** [Seok June Park](https://apify.com/kdatafactory) (community)
- **Categories:** E-commerce, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 results

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/platform/actors/running/actors-in-store#pay-per-event

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

## K-Pop Photocard Price Index 📊🎴

The **first K-pop photocard price index built on Korean-origin market data**. This actor
samples live listings from [Pocamarket](https://pocamarket.com) (포카마켓) — the global
marketplace where K-pop fans buy and resell photocards — and aggregates them into one
clean index row per **(artist, member)**: listing count, **median / min / max USD asking
price**, average wish count (demand signal), and sample listing URLs.

Sellers and buyers on eBay, Mercari, or Depop usually price photocards by guessing from
scattered listings. This index lets you **price against the origin market** instead.

> **Try it free.** Apify's free plan includes $5 of monthly platform credit — roughly **1,600 results** from this actor, and one run emits only ~20–150 index rows, so that's **months of daily index snapshots**, no credit card required. Set your input, click Start, and export JSON/CSV/Excel.

***

### 🚀 What it does

1. **Samples** up to `maxListings` photocard listings from Pocamarket's public catalog API
   (each listing already carries the lowest current USD asking price across sellers).
2. **Groups** them by the catalog's own artist / member labels.
3. **Aggregates** each group into one index row: `listing_count`,
   `median_price_usd`, `min_price_usd`, `max_price_usd`, `avg_wish_count`, and up to 3
   `sample_urls`.

Give it a list of artists to build a focused per-member index, or leave `artists` empty to
index the top (newest) listings across the whole catalog.

> **Privacy first:** this is an **aggregate index** — card + price statistics only. The
> catalog API carries no seller nicknames, IDs, or profiles, and no seller identity exists
> anywhere in this actor's pipeline or output.

***

### 📥 Input

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `artists` | array | `[]` | Artist/group names to index (e.g. `SEVENTEEN`, `ATEEZ`, `NewJeans`). Empty = top listings across the whole catalog. |
| `maxListings` | integer | `400` | How many listings to sample and aggregate (cap 2,000, split evenly across artists). More listings = deeper groups, more reliable medians. |
| `minListingsPerGroup` | integer | `3` | Drop (artist, member) groups backed by fewer priced listings — thin groups make noisy medians. |
| `proxyConfiguration` | object | off | Optional Apify proxy. Not required — enable one if you hit rate limits at scale. |

**Input example — per-member price index for two groups:**

```json
{
  "artists": ["SEVENTEEN", "ATEEZ"],
  "maxListings": 400,
  "minListingsPerGroup": 3
}
```

**You are billed per INDEX ROW emitted (typically 20–150 per run), not per listing sampled.**

***

### 📤 Output

Each (artist, member) group is one dataset record in this shape (real sample from a live run):

```json
{
  "source": "pocamarket_index",
  "artist": "ATEEZ",
  "member": "SEONGHWA",
  "listing_count": 6,
  "median_price_usd": 9.8,
  "min_price_usd": 9.8,
  "max_price_usd": 24.5,
  "avg_wish_count": 9.3,
  "sample_urls": [
    "https://pocamarket.com/search?photo_card_id=484215",
    "https://pocamarket.com/search?photo_card_id=485019",
    "https://pocamarket.com/search?photo_card_id=487148"
  ],
  "scraped_at": "2026-07-10T15:17:36.542+09:00"
}
```

**Field notes**

- `listing_count` — number of distinct priced photocards sampled for this group.
- `median_price_usd` / `min_price_usd` / `max_price_usd` — statistics over each card's
  **lowest current asking price** (after any active discount), in **USD** (Pocamarket's
  global marketplace prices in USD).
- `avg_wish_count` — mean wishlist count across the group's cards, a **demand signal**.
- `sample_urls` — up to 3 example catalog listings from the group, most-wished first.
- `artist` / `member` — the **catalog's own labels** (e.g. `Seventeen`, `SEUNGKWAN`).
  Unit and full-group cards carry member labels like `Unit` / `Group` and form their own rows.
- A 20-row real sample lives in [`samples/sample-output.json`](samples/sample-output.json).

***

### 💡 Use cases

- **Resale pricing** — price your photocards on eBay / Mercari / Depop against the
  **Korean-origin market median** instead of guessing from three stale listings.
- **Arbitrage spotting** — compare origin-market medians to Western marketplace prices and
  find the spread per artist/member.
- **Collectible market analytics** — track which members command price premiums, and how
  demand (`avg_wish_count`) maps to price.
- **Trend monitoring** — schedule daily runs and chart median movement per member around
  comebacks, tours, and enlistments.
- **AI agents & LLM pipelines** — a compact, numeric index table is far cheaper to feed an
  agent than thousands of raw listings.

***

### 🌐 Data source

This actor reads Pocamarket's **public** catalog JSON API — the same one that powers
pocamarket.com — and aggregates in one pass. No login, no private API, no HTML scraping.
The endpoint returns card-level data with the lowest asking price already consolidated
across sellers, so **no proxy is required** in most runs; enable an Apify proxy for IP
diversity at scale.

Want the underlying card-level rows instead of the index? Use the companion
[pocamarket-scraper](https://apify.com/kdatafactory/pocamarket-scraper) actor.

***

### ⚠️ Known limitations (honest notes)

- **Asking-price index, not sold-price index.** Statistics are computed over current
  (lowest) asking prices, not completed transactions.
- **Sample-based medians.** Each run samples up to `maxListings` listings (newest first),
  so medians describe the current market surface, not the full historical order book.
  Raise `maxListings` for deeper groups.
- **Thin groups are dropped** below `minListingsPerGroup` (default 3). If *no* group
  reaches the threshold (tiny `maxListings`), the actor emits all observed groups rather
  than failing, and logs a warning.
- **`artists` is a keyword search.** Results are grouped by the catalog's own labels
  (e.g. `Seventeen`, not `SEVENTEEN`), and a keyword can occasionally match cards of other
  artists; such stray groups are usually removed by `minListingsPerGroup`.
- **No card\_type / album-era breakdown in v0.1.** Grouping is per (artist, member) only.

***

### ⚖️ Rate & legality note

- Only **public, non-personal** catalog data is read — the same listings anyone sees on
  Pocamarket without logging in — and only **aggregated statistics** are emitted.
  **No personal data**: the catalog API carries no seller nicknames, IDs, or profiles, and
  this actor's output contains no seller identity of any kind. `artist`/`member` are
  public commercial attribution (like an author name on a book).
- Requests are **rate-limited** (sequential pages, ≥500 ms delay) to stay light on the site.
- You are responsible for complying with Pocamarket's Terms of Service and applicable law
  in your jurisdiction. Use the data for research, pricing, and analytics — not to
  replicate the platform.

***

### ❓ FAQ

**Is it legal to scrape this data?**
This actor reads only public, non-personal catalog data and outputs aggregated statistics
per artist/member. No seller data is collected at any stage. You are responsible for how
you use the data; see the rate & legality note above.

**What does it cost in practice?**
$3.00 per 1,000 results (launch pricing) + a few cents of platform usage. One run emits
roughly 20–150 index rows, so a **daily snapshot costs well under $0.50/day**. Apify's
free $5 monthly credit covers ~1,600 results.

**Do I need to configure proxies?**
No — the default settings work out of the box. Optionally, enable an Apify proxy for IP
diversity when running at scale.

**How fresh is the data?**
Every run samples the live Pocamarket catalog at run time. Schedule the actor for
recurring index snapshots and diff the medians.

**Why do median and min sometimes match?**
Popular cards often have many listings at the same lowest asking price, so the median can
sit at the minimum. That's the real market shape, not a bug.

**What is NOT included?**
Sold/transaction prices (asking prices only), card\_type / album-era breakdowns (grouping
is artist + member), raw card-level rows (use
[pocamarket-scraper](https://apify.com/kdatafactory/pocamarket-scraper) for those), and
any seller identity (by design, never).

***

### 🤖 Use with AI agents (MCP)

Call this Actor as a tool from Claude or any MCP-compatible AI agent — no glue code. Point your MCP client at Apify's server, scoped to this Actor:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=kdatafactory/kpop-photocard-index",
      "headers": { "Authorization": "Bearer <YOUR_APIFY_TOKEN>" }
    }
  }
}
```

Your agent can then pull K-pop photocard median prices by member on demand — no scraping code in your app. Grab a free token from [Apify → Integrations](https://console.apify.com/settings/integrations).

### 🇰🇷 More Korean data actors

This actor is part of a suite of Korean-platform scrapers by the same maintainer:

- [pocamarket-scraper](https://apify.com/kdatafactory/pocamarket-scraper) — the raw card-level listings behind this index: per-card prices, stock, wishes.
- [ktown4u-scraper](https://apify.com/kdatafactory/ktown4u-scraper) — K-pop albums & official merch prices from a global K-pop shop.
- [bunjang-scraper](https://apify.com/kdatafactory/bunjang-scraper) — Korea's top secondhand marketplace, resale listings & prices.

Browse all: [apify.com/kdatafactory](https://apify.com/kdatafactory)

***

### 🏃 Run it

On Apify: set your input and click **Start**. Locally:

```bash
npm install
## put your input in storage/key_value_stores/default/INPUT.json
npm start
```

Results land in the default dataset (Apify) or `./storage/datasets/default` (local).

***

*If this actor saves you time, a rating on the [Store page](https://apify.com/kdatafactory/kpop-photocard-index) helps a solo maintainer a lot. Found an issue? Open it in the Issues tab — I respond fast.*

# Actor input Schema

## `artists` (type: `array`):

Artist / group names to index (e.g. 'SEVENTEEN', 'ATEEZ', 'NewJeans'). Each entry is searched against the Pocamarket catalog and the results are grouped by the catalog's own artist/member labels. Leave empty to index the top (newest) listings across the whole catalog.

## `maxListings` (type: `integer`):

How many catalog listings to fetch and aggregate (split evenly across artists). More listings = deeper groups and more reliable medians. Note: you are billed per INDEX ROW emitted, not per listing sampled.

## `minListingsPerGroup` (type: `integer`):

Drop (artist, member) groups backed by fewer than this many priced listings — thin groups make noisy medians. If no group reaches the threshold, the actor emits all observed groups instead of failing.

## `proxyConfiguration` (type: `object`):

Optional Apify proxy. The catalog API usually works on a direct connection; enable a proxy (e.g. RESIDENTIAL) only if you hit rate limits at scale.

## Actor input object example

```json
{
  "artists": [
    "SEVENTEEN",
    "ATEEZ"
  ],
  "maxListings": 400,
  "minListingsPerGroup": 3,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# 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 = {
    "artists": [
        "SEVENTEEN",
        "ATEEZ"
    ],
    "maxListings": 400,
    "minListingsPerGroup": 3
};

// Run the Actor and wait for it to finish
const run = await client.actor("kdatafactory/kpop-photocard-index").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 = {
    "artists": [
        "SEVENTEEN",
        "ATEEZ",
    ],
    "maxListings": 400,
    "minListingsPerGroup": 3,
}

# Run the Actor and wait for it to finish
run = client.actor("kdatafactory/kpop-photocard-index").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "artists": [
    "SEVENTEEN",
    "ATEEZ"
  ],
  "maxListings": 400,
  "minListingsPerGroup": 3
}' |
apify call kdatafactory/kpop-photocard-index --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=kdatafactory/kpop-photocard-index",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/EEsQJ0ekvdRO1qtqv/builds/VyQBkPhb5BvdFzByO/openapi.json