# TCDB Scraper - Trading Card Database Catalog (`lulzasaur/tcdb-scraper`) Actor

Scrape trading card catalog data from The Trading Card Database (tcdb.com). Get card title, player/subject, set, year, card number, team, attributes (RC/variations), image, and URLs. Search by set query like '1986 Fleer Basketball' or pass set URLs/IDs.

- **URL**: https://apify.com/lulzasaur/tcdb-scraper.md
- **Developed by:** [lulz bot](https://apify.com/lulzasaur) (community)
- **Categories:** E-commerce
- **Stats:** 10 total users, 3 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.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/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

## TCDB Scraper - Trading Card Database Catalog

Scrape trading-card catalog data from **[The Trading Card Database (tcdb.com)](https://www.tcdb.com)** — one of the largest community-maintained catalogs of sports and non-sport trading cards, covering hundreds of thousands of sets and millions of individual cards.

Search by set (e.g. `1986 Fleer Basketball`) or point the scraper at specific set URLs / IDs, and get clean, structured card records: player/subject, set, year, card number, team, attributes (rookie cards, variations), image, and canonical URLs.

### What it extracts

For every card in a matched set's checklist:

| Field | Description |
|-------|-------------|
| `title` | Full card title, e.g. `1986-87 Fleer #57 Michael Jordan` |
| `subject` | Player / subject name |
| `cardNumber` | Card number within the set (`57`, `NNO`, `AR-1`, ...) |
| `setName` | Set name |
| `year` | Set year (`1986`, `1986-87`, ...) |
| `sport` | Sport / category (Basketball, Baseball, Football, Non-Sport, ...) |
| `team` | Team / franchise (where present) |
| `attributes` | Inline flags: `RC` (rookie), `SP`, `SSP`, `VAR` (variation), `AU`, `RELIC`, `MEM` |
| `isRookie` | Convenience boolean derived from `attributes` |
| `setId` / `cardId` | TCDB internal set (`sid`) and card (`cid`) identifiers |
| `imageUrl` | Card thumbnail image URL |
| `cardUrl` | Canonical TCDB card page URL |
| `setUrl` | Canonical TCDB set page URL |
| `searchQuery` | The input query this record came from |
| `scrapedAt` | ISO 8601 timestamp |

### Input

```json
{
    "searchQueries": ["1986 Fleer Basketball", "2009 Donruss Gridiron Gear Football"],
    "maxResults": 200,
    "scrapeDetails": true,
    "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"] }
}
```

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `searchQueries` | array of strings | `["1986 Fleer Basketball"]` | Set queries (`year + set name + sport`), full set URLs, or `sid/<id>` references |
| `maxResults` | integer | `200` | Max card records per query |
| `scrapeDetails` | boolean | `true` | Follow pagination to capture entire large sets; disable for first-page-only (faster) |
| `proxyConfiguration` | object | RESIDENTIAL | Proxy settings (residential recommended — see below) |

#### Query formats

- **Free text**: `1986 Fleer Basketball` — the scraper detects the year (`1986`) and sport (`Basketball`), browses that sport/year on TCDB, matches set names containing the remaining keywords (`fleer`), and scrapes each matching set's full checklist.
- **Set URL**: `https://www.tcdb.com/ViewSet.cfm/sid/2067/1986-87-Fleer`
- **Set ID**: `sid/2067`

### Notes on Cloudflare

TCDB is protected by Cloudflare's managed challenge. This Actor uses a real headless browser (Playwright/Chromium) and a **residential proxy by default** to clear the challenge, retiring the browser between requests to keep the challenge state fresh. Datacenter proxies typically get stuck on the security interstitial — keep the residential setting unless you have a reason to change it.

### Example output

```json
{
    "title": "1986-87 Fleer #57 Michael Jordan",
    "subject": "Michael Jordan",
    "cardNumber": "57",
    "setName": "1986-87 Fleer",
    "year": "1986-87",
    "sport": "Basketball",
    "team": "Chicago Bulls",
    "attributes": ["RC"],
    "isRookie": true,
    "setId": "2067",
    "cardId": "12345",
    "imageUrl": "https://www.tcdb.com/Images/Thumbs/Basketball/2067/...",
    "cardUrl": "https://www.tcdb.com/ViewCard.cfm/sid/2067/cid/12345/1986-87-Fleer-57-Michael-Jordan",
    "setUrl": "https://www.tcdb.com/ViewSet.cfm/sid/2067",
    "searchQuery": "1986 Fleer Basketball",
    "scrapedAt": "2026-07-03T06:40:00.000Z"
}
```

### Use cases

- Build price-guide / arbitrage tools by combining card checklists with market data
- Populate collection-management apps with accurate set checklists
- Research player card catalogs across years and manufacturers
- Feed card metadata into search, matching, and grading pipelines

### Pricing

Pay-per-result: you are charged a small fee for each card record returned, plus a tiny per-run start fee. No monthly subscription.

# Actor input Schema

## `searchQueries` (type: `array`):

One or more trading-card set searches. Each entry may be: a set query like '1986 Fleer Basketball' or '2009 Donruss Gridiron Gear Football' (year + set name + sport), a full TCDB set URL (e.g. https://www.tcdb.com/ViewSet.cfm/sid/2067/1986-87-Fleer), or a set id like 'sid/2067'. For free-text queries the scraper browses that sport & year on TCDB, matches set names by keyword, and scrapes each set's full checklist.

## `maxResults` (type: `integer`):

Maximum number of card records to scrape per search query. Default is 200.

## `scrapeDetails` (type: `boolean`):

When enabled, follows pagination to capture every card in large sets (100+ cards). When disabled, only the first checklist page (up to 100 cards) per set is scraped — faster and cheaper.

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

Proxy settings. TCDB is protected by Cloudflare, so a RESIDENTIAL proxy is strongly recommended (and used by default). Datacenter IPs typically get stuck on the security challenge.

## Actor input object example

```json
{
  "searchQueries": [
    "1986 Fleer Basketball"
  ],
  "maxResults": 200,
  "scrapeDetails": true,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# 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 = {
    "searchQueries": [
        "1986 Fleer Basketball"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("lulzasaur/tcdb-scraper").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 = { "searchQueries": ["1986 Fleer Basketball"] }

# Run the Actor and wait for it to finish
run = client.actor("lulzasaur/tcdb-scraper").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 '{
  "searchQueries": [
    "1986 Fleer Basketball"
  ]
}' |
apify call lulzasaur/tcdb-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,lulzasaur/tcdb-scraper"
        }
    }
}

```

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/ISrazjWOk4ijUA6jN/builds/9qyNSATePSfxtypiX/openapi.json