Grand Archive Importer Technical Overview

The Grand Archive importer fetches card data from the official GA API (api.gatcg.com) and enriches products with TCGPlayer IDs from TCGCSV (category 74) for pricing. It extends BaseImporter.

Data Sources

The GA API drives what products exist. TCGCSV is used only to attach TCGPlayer product IDs so the price importer can fetch prices.

Import Flow

TCGPlayer Price Matching Strategy

The Problem

The GA API has 54 expansions, TCGPlayer has 44 groups. Names and codes differ:

The Solution: Static Deterministic Map

Every GA set code is mapped to TCGPlayer group ID(s) in GA_CODE_TO_TCGPLAYER_GROUP. This follows the same pattern as FAB’s FAB_SLUG_TO_TCGPLAYER_GROUP.

// Examples from GA_CODE_TO_TCGPLAYER_GROUP
"HVN":       [24070],                       // 1:1 exact match
"ReC-AUR":   [24591],                       // Name mismatch, verified groupId
"EVP":       [23125, 23436, 23784, 24252],  // 1:many (search all 4 groups)
"P24":       [23133],                       // many:1 (all promo years → same group)
"HVN 1st":   [24070],                       // 1st ed redirects to base set
"FTCA":      [],                            // Known absent — don't search

Within a mapped group, products match by print number (primary) + card name (secondary) + finish (tiebreaker).

Coverage: 84-88% of Products

How Product Matching Works

Once the expansion is mapped to TCGPlayer group(s), individual products are matched:

1. Print number match — GA API uses zero-padded 3-digit numbers ("001"), TCGPlayer uses the same format ("001"). Both sides are normalized (strip leading zeros) for comparison.
2. Name match — Exact match after normalization. TCGPlayer appends (CPR), (115) to some promo card names — the normalizer strips parenthesized suffixes before comparing.
3. Finish tiebreaker — When the same card exists as both Normal and Foil on TCGPlayer, the matcher scores subTypeName (“Normal” → Standard, “Foil” → Foil) to pick the correct product.

Tested Results (Real Data)

What Has No Price Data

5 sets (~370 products) have no TCGPlayer equivalent:

These will get prices if/when TCGPlayer adds them. The static map entry [] means the matcher won’t waste time searching.

Full Expansion Mapping Table

Code Locations