# Pokémon Card Price Analyzer (`trovevault/pokemon-card-price-analyzer`) Actor

Search current ungraded Pokémon card prices by name or set, with optional collector-number, variant, and asking-price filters.

- **URL**: https://apify.com/trovevault/pokemon-card-price-analyzer.md
- **Developed by:** [Trove Vault](https://apify.com/trovevault) (community)
- **Categories:**
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.85 / 1,000 cards

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#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

## Pokémon Card Price Analyzer

Find current ungraded Pokémon card prices for one or several names and sets. Searching for `Pikachu` and `Squirtle` returns priced matching models for both across every set; searching for `Base Set` alone returns all priced cards in that set. Combine the two lists to narrow the results.

It resolves the exact card inside the requested set, distinguishes printings such as Unlimited, 1st Edition, Shadowless, Holo, and Reverse Holo, then returns one row per priced variant.

The Actor covers ungraded cards only. It does not estimate PSA, BGS, CGC, or other graded values, and it does not infer a card's physical condition from a photo or description.

### Why use this Actor

Pokémon characters can appear hundreds of times, the same collector number can exist in different sets, and vintage cards can have materially different variants. A useful search must show each resolved card separately rather than attaching one price to the character name.

This Actor searches broadly across every supplied name or set and removes overlapping results. That makes it useful when you want to:

- Value a personal Pokémon card collection in a consistent format.
- Enrich inventory records with a current ungraded market benchmark.
- Compare a marketplace listing or dealer offer with the market price.
- Monitor the same cards regularly through scheduled Apify runs.
- Export price data to CSV, JSON, Excel, Google Sheets, or a database.

### What it produces

Each dataset row represents one resolved card variant in one currency. The most useful fields are:

- `cardName`, `setName`, and `collectorNumber`: the resolved card identity. `collectorNumber` is the number printed on the card, not the number of cards for sale.
- `variant`: the resolved printing and finish, such as `Unlimited Normal` or `1st Edition Shadowless Holo`.
- `marketPrice`: the main current ungraded market benchmark.
- `lowPrice`, `midPrice`, and `highPrice`: available market range observations. Individual high values can contain exceptional listings or outliers, so the market price should normally be the primary benchmark.
- `average1Day`, `average7Days`, and `average30Days`: rolling European observations returned when EUR is selected and the values are available.
- `candidatePrice`: the optional price supplied with the card.
- `differenceAmount` and `differencePercent`: the candidate price minus the market benchmark.
- `dealStatus`: a simple position label based on a fixed 15% band.
- `priceUpdatedAt`: the timestamp associated with the market observation.
- `imageUrl`: a high-resolution card image when available.

### Input

The form uses ordinary lists, so no JSON editing is needed. Enter at least one card name or set name and add each value on a separate line. Names within the list are combined with OR, sets within the list are combined with OR, and the two lists are combined with AND.

```json
{
  "cardNames": ["Pikachu", "Squirtle"],
  "currency": "USD",
  "runId": "collection-2026-08"
}
```

#### Input fields

- `cardNames`: optional list of English card names or fragments. `Pikachu` also matches Pikachu ex, Pikachu V, and Flying Pikachu. Add `Squirtle` on another line to return both groups.
- `setNames`: optional list of English set names. Used alone, `Base Set` and `Pokémon 151` return every priced card in both sets. With card names present, results must belong to one of the selected sets.
- `candidatePrice`: optional listing, offer, or purchase price. It must use the selected currency.
- `currency`: `USD` for US market observations or `EUR` for European market observations.
- `datasetId`: optional existing Apify dataset ID. Results are written to the run's default dataset and also appended to this dataset.
- `runId`: optional external batch reference copied into each result row.

Broad name and set searches can return many rows. Use the set list to narrow a search. Collector number and variant are returned for every result so you can identify the exact card and printing; they are not required as inputs. Overlapping searches are deduplicated automatically.

### Run through the API

Replace `YOUR_APIFY_TOKEN` with your Apify API token:

```bash
curl -X POST "https://api.apify.com/v2/acts/trovevault~pokemon-card-price-analyzer/runs?waitForFinish=120" \
  -H "Authorization: Bearer YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cardNames":["Pikachu","Squirtle"],"setNames":["Base Set","Pokémon 151"],"currency":"USD"}'
```

### Output example

```json
{
  "cardName": "Pikachu",
  "setName": "Base Set",
  "collectorNumber": "58",
  "variant": "Unlimited Normal",
  "imageUrl": "https://assets.tcgdex.net/en/base/base1/58/high.webp",
  "currency": "USD",
  "marketPrice": 16.5,
  "lowPrice": 3.99,
  "midPrice": 8.99,
  "highPrice": 1000,
  "candidatePrice": 25,
  "differenceAmount": 8.5,
  "differencePercent": 51.52,
  "dealStatus": "above_market",
  "priceUpdatedAt": "2026-08-27T15:00:45.974Z",
  "runId": "collection-2026-08"
}
```

Prices in this example are illustrative snapshots and will change as the market data updates.

### Candidate price comparison

When `candidatePrice` is present, the Actor compares it with `marketPrice`:

- `below_market`: candidate is at least 15% below the market benchmark.
- `near_market`: candidate is within 15% of the market benchmark.
- `above_market`: candidate is at least 15% above the market benchmark.

For example, if the market price is 100 and the candidate price is 80, `differenceAmount` is -20, `differencePercent` is -20, and `dealStatus` is `below_market`.

This label is mechanical. It does not assess card condition, authenticity, seller reputation, shipping, taxes, language, print defects, or future price movement. Treat it as a screening aid, not financial advice.

### Variant matching

Variant identification matters most for vintage cards. The Actor keeps distinct catalog printings and finishes as separate output rows.

Examples:

- `Unlimited Holo` will not be matched to an Unlimited non-holo printing.
- `1st Edition Shadowless Holo` will not be matched to the ordinary Unlimited Holo printing.
- `Reverse Holo` is kept separate from Holo and Normal when the catalog provides that distinction.
- Special stamps and unusual sizes can appear in the returned variant label.

Only variants with a usable price in the selected currency are returned. The Actor does not merge distinct printings into one price.

### USD and EUR coverage

USD and EUR represent different market observations, not a currency conversion of the same number.

For USD, `marketPrice`, `lowPrice`, `midPrice`, and `highPrice` are returned when available for the resolved finish. For EUR, the Actor uses the available European trend or rolling-average values for the market benchmark and can also return one-day, seven-day, and thirty-day averages.

Coverage can differ by variant. A vintage European variant may have EUR data but no usable USD observation, or the reverse. The Actor does not invent a price and does not convert between currencies when the requested market is missing.

### Missing cards and run summary

If a name or set is unavailable, the Actor does not create a misleading result row. The reason is recorded in the run summary instead.

At the end of every run, the `RUN_SUMMARY` record contains:

```json
{
  "requestedCards": 2,
  "matchedCards": 0,
  "resultRows": 0,
  "catalogCardsScanned": 1,
  "sourceFailures": 0,
  "selectedCurrency": "USD",
  "misses": [
    {
      "index": 0,
      "query": "Example card",
      "reason": "No cards matched the supplied name"
    }
  ],
  "completedAt": "2026-08-28T15:19:02.160Z"
}
```

Common reasons for a miss are an incorrect name, an incorrect set name, or no usable price in the selected currency.

### Using the results

Results can be downloaded as JSON, CSV, Excel, XML, RSS, or HTML, or consumed through the Apify API, webhooks, schedules, and integrations. For historical data, use `cardName`, `setName`, `collectorNumber`, `variant`, `currency`, and `priceUpdatedAt` as the main dimensions.

### Data limitations

Pokémon card prices are volatile and may be delayed, sparse, or affected by outlier listings. The observed price does not guarantee that a card will sell at that value. An ungraded card's actual value depends heavily on its physical condition, authenticity, language, edition, finish, and buyer demand.

The Actor matches catalog identity and printing information; it does not inspect a physical card. Always verify the returned image, set, collector number, and variant before using the result in a high-value decision. For expensive vintage cards, manual authentication and condition review remain essential.

Market coverage comes from public card-catalog observations available at run time. Coverage and update frequency can change. When a market benchmark is unavailable, the Actor returns no price row.

Pokémon and related names are trademarks of their respective owners. This Actor is an independent data-processing tool and is not affiliated with, endorsed by, or sponsored by The Pokémon Company, Nintendo, Creatures, Game Freak, TCGplayer, or Cardmarket.

### Support

If a card does not resolve, include the exact input object, currency, and `RUN_SUMMARY` reason when reporting the issue. Do not include private Apify tokens or credentials.

# Actor input Schema

## `cardNames` (type: `array`):

English card names or fragments. Pikachu also finds models such as Pikachu ex and Pikachu V. Add Squirtle on another line to return both groups.

## `setNames` (type: `array`):

English set names, for example Base Set or Pokémon 151. With no card names, every priced card from each set is returned. With card names, the sets limit those searches.

## `currency` (type: `string`):

USD uses US market observations. EUR uses European market observations.

## `candidatePrice` (type: `number`):

Price you want to compare with the market benchmark, in the currency selected above.

## `datasetId` (type: `string`):

Existing Apify dataset ID where the same result rows should also be stored.

## `runId` (type: `string`):

Reference copied into each result so you can join it to your own workflow.

## Actor input object example

```json
{
  "cardNames": [
    "Pikachu",
    "Squirtle"
  ],
  "currency": "USD"
}
```

# Actor output Schema

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

No description

## `runSummary` (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 = {
    "cardNames": [
        "Pikachu",
        "Squirtle"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("trovevault/pokemon-card-price-analyzer").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 = { "cardNames": [
        "Pikachu",
        "Squirtle",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("trovevault/pokemon-card-price-analyzer").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 '{
  "cardNames": [
    "Pikachu",
    "Squirtle"
  ]
}' |
apify call trovevault/pokemon-card-price-analyzer --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,trovevault/pokemon-card-price-analyzer"
        }
    }
}

```

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/7CbEk2UeeTTYcEdLQ/builds/edWrciSW5Ul3hhvbH/openapi.json