cardcorpus

Variants

One card on a checklist can exist as several different physical cards: holo and reverse holo, 1st Edition and Unlimited, a stamped promo, a printing error. Each is a variant, listed under its card.

A card's variants

Every card has a variants list with at least one variant. The first is the standard one: the variant people mean when they name the card. If your app doesn't care about variants, use the card and stop there.

A variant's id is unique within its card, so a variant's address is three ids: set, card and variant. Prices and marketplace links are keyed the same way.

curl https://pokemon.cardcorpus.com/v1/sets/english/base-set.json
{
  "cards": [
    {
      "id": "4",
      "name": "Charizard",
      "variants": [
        {
          "id": "unlimited-holo",
          "name": "Unlimited",
          "role": "standard",
          "finish": "holo",
          "edition": "unlimited",
          "tell": { "text": "A shadow around the picture; the main run" },
          "picture": { "front": { "image": "2aca2cf3e9ca6703b5edea32eb3177ea" } },
          // … 1 more field
        },
        {
          "id": "first-edition-holo",
          "name": "1st Edition",
          "role": "print_run",
          "finish": "holo",
          "edition": "first_edition",
          "tell": {
            "text": "A 1st Edition symbol, and no shadow around the picture"
          },
          "picture": { "front": { "image": "11d15e793a13ff214416ce28d1268ed7" } },
          // … 3 more fields
        },
        // … 5 more
      ],
      // … 15 more fields
    },
    // … 101 more
  ],
  // … 18 more fields
}
200application/json: one card with two of its variants

Telling variants apart

Each variant says what it is in two ways. tell.text is a sentence a person can check against the card in their hand. The coded fields (finish, edition, stamp and the others) are for your code to filter on.

differsFromStandard holds just the fields that set this variant apart from the standard one, which is usually what a label needs: "1st Edition", "Reverse holo".

variants.js
const get = (path) =>
  fetch(`https://pokemon.cardcorpus.com/v1/${path}`).then((res) => res.json());

const set = await get("sets/english/base-set.json");
const charizard = set.cards.find((c) => c.number.printed === "4/102");

// Every variant says how to tell it apart
for (const variant of charizard.variants) {
  console.log(`${variant.name}: ${variant.tell.text}`);
}
Prints
Unlimited: A shadow around the picture; the main run
1st Edition: A 1st Edition symbol, and no shadow around the picture
Shadowless: No shadow around the picture
4th print: Like Unlimited, but a smaller run with a 1999-2000 copyright year
Black dot on the "t": A small black ink dot over the "t" of "Nintendo" in the copyright line.
Shadowless · Disco holo: No drop shadow around the picture, thin HP and attack text, and no 1st Edition symbol; Trainers and Energy read "© 1995, 96, 98, 99 Nintendo". Holo foil of small, tightly packed round dots, a pattern no released card uses: Base Set test prints only.
Cosmos holo: Holo foil of dots and circles of different sizes, like a night sky.

Labels for the coded words

Values like holo and first_edition are words from vocabulary.json. Look one up to get the label to show for it and, for many, how to spot it on a card. More in Conventions.

labels.js
const get = (path) =>
  fetch(`https://pokemon.cardcorpus.com/v1/${path}`).then((res) => res.json());

const words = await get("vocabulary.json");
const set = await get("sets/english/base-set.json");
const [variant] = set.cards.find((c) => c.name === "Charizard").variants;

// A coded word, the label to show for it, and how to spot it
console.log(variant.finish, "->", words.finish[variant.finish].label);
console.log(words.finish[variant.finish].tell);
Prints
holo -> Holo
The picture shines; the rest of the card doesn't.

The variant object

idstringalways present
The variant's id, unique within its card: its physical axes as a slug, or "plain". Treat it as opaque: it never changes once published.
namestringalways present
What the card's variant strip calls it (see the guide).
roleword from vocabulary.rolealways present
What this variant is on its card; variants are listed in role order (see the guide).
finishword from vocabulary.finish
Its finish.
editionword from vocabulary.edition
Its edition.
stampword from vocabulary.stamp
The stamp it carries.
tellobject
How to spot it on the card, in a sentence or two.
differsFromStandardobject
Its axes that the card's standard variant doesn't share (all of them on a card with no standard variant); none on the standard variant.
pictureobject
The variant's picture (see the guide): its own, or, with front.of, another variant's standing in for one it lacks (the standard variant's; on the standard variant, the first other variant's); and its back, where that is unlike the usual one.
distributionslist of pointer
How the variant was handed out beyond its set's own distributions: each distribution by its pointer, with its name and category, and as and region where they apply.
8 more fields
materialword from vocabulary.material
What it is printed on, where that isn't ordinary card.
serialCodestring
Its serial code; always present on a serial_code copy.
serialCodeVariantOfpointer
Another code of the same physical version, by its pointer; always present on a serial_code copy.
errorStateword from vocabulary.errorState
The printing error it shows.
eReaderStripenum
What it prints where its card prints the e-Reader strip (the card's eReaderLayout), as its own picture shows: the dot code, holo bars in its place (a reverse holo, a holo rare), or nothing (blank: an EX card without a strip). Absent where nobody has looked (see the guide).
editionMarkenum
The edition mark it prints: first_edition, the 1st Edition symbol. Its edition's mark (vocabulary edition, mark) unless the variant says otherwise, as Base Set Machamp's stamped ©1999-2000 4th print does. Absent where it prints none (see the guide).
printRunword from vocabulary.edition
The edition of the set's print run (its printRuns) the variant came out in, where the set lists that run: look it up there. Equal to edition wherever both are present; unlimited on a variant with no edition whose set has runs; absent where the variant's edition has no known place among the set's runs (see the guide).
descriptionobject
What we wrote about the variant, for people to read, and the pages it draws on (see the guide).