cardcorpus

Cards

A card is one entry in a set's checklist. It lives in its set's file, and its address is its set's id plus its own.

Get a set's cards

Cards come with their set: GET /v1/sets/{set}.json and read cards. They are in number order.

A card's id is unique within its set, so a card's full address is two ids: the set (english/base-set) and the card (4). Store those, not names or urls: ids never change once published.

There is no url for a single card. A set file is small over the wire (Base Set is about 45 KB compressed), so fetch the set and pick the card out.
set.js
const get = (path) =>
  fetch(`https://pokemon.cardcorpus.com/v1/${path}`).then((res) => res.json());

const set = await get("sets/english/base-set.json");

console.log(`${set.name}: ${set.cards.length} cards`);
for (const card of set.cards.slice(0, 4)) {
  console.log(card.number.printed, card.name, "·", card.rarity);
}
Prints
Base Set: 102 cards
1/102 Alakazam · Holo Rare
2/102 Blastoise · Holo Rare
3/102 Chansey · Holo Rare
4/102 Charizard · Holo Rare

The card object

The first fields are what any card list shows. variants and links are where CardCorpus goes further: see Variants and Links between cards.

idstringalways present
The card's id, unique in its set. Treat it as opaque: it never changes once published.
namestringalways present
The card's name as it prints it, in its language: "リザードン" on a Japanese Charizard. Where no source gives the printed name yet, its English name (see the guide).
numberobject
Its number as printed ("4/102", "SWSH001"), and that number without its set total.
rarityword from vocabulary.rarity
Its rarity, as its mark reads (see the guide).
cardTypeword from vocabulary.cardType
Pokémon, Trainer or Energy.
languageword from vocabulary.languagealways present
The language its text is printed in: its set's, or another where its product held a foreign print (see the guide). Every card has one.
creditstring
The credit as printed ("CR CG gangs & K. Hoshiba").
artistslist of pointer
The people the credit names, in credit order, each by pointer with the name as this card prints it; a director's credit names no one.
specieslist of pointer
The species it shows, each once, in the order the card shows them, each with the forms of it the card shows where that is more than its ordinary form.
releasedobjectalways present
When the card first came out, in any of its variants: its own date, or, in a set whose cards came out together, the set's (see the guide).
pictureobject
The picture to show for the card (see the guide): front.image, and front.of, the variant it is a picture of (its default variant, another variant standing in, or, for a reprint with no picture of any variant, its original's); back, where its back is unlike the usual one; oversized where the card only came as a jumbo or its picture is a jumbo variant's.
variantslist of objectalways present
Its variants, in role order; the standard one, or the first on a test-only card, supplies the card picture.
linksobject
Its links to other cards: in a list, only its painting.
13 more fields
descriptionobject
What we wrote about the card, for people to read, and the pages it draws on (see the guide).
tellobject
How to tell this card's print where it differs from its set's tell.
eReaderLayoutenum
Where it prints its e-Reader strip, as its pictures show: e_card (along the bottom, under the number, and down the left edge, as Expedition to Skyridge do) or ex (one strip along the bottom, under the weakness row, as the EX sets do). Absent where it prints none or nobody has looked (see the guide).
characterslist of pointer
The people the card names, in the card's order: its subject (a Supporter's trainer), or the owner of its Pokémon (Misty's Psyduck).
differsInSetobject
Present where its set prints the same painting on other cards too (its links.parallels, and any other card of the set around that painting): what tells this card from them, as the axes of its default variant that not all of them share, such as {"finish": "pokeball_pattern"} (see the guide).
printVersioninteger
Which of a pair it is, 1 or 2, on the rare pairs of different cards in one set with the same name that the numbering doesn't tell apart. The Celadon City Gym deck's two Erika's Oddish, both numbered No. 043, are 1 and 2; so are Pikachu World Collection's two numberless Pikachu, the blue binder's and the green binder's. It counts within the pair and is not a pointer into the set's versions (that is onlyInSetVersions).
onlyInSetVersionslist of pointer
Present where its set is sold in versions (the set's versions) and this card is in only some of them: those versions. A card without it is in every version (see the guide).
piecesobject
Present where the card is one piece of a card printed in pieces, a LEGEND's half or a V-UNION's quarter: the whole card's pieces (see the guide).
printRunslist of pointer
On a card printed in more than one run: its standard variant and print runs, in printing order (see the guide).
setstringalways present
The set's id (sets/{catalog}.json).
englishNamestring
The card's name in English, on every card, the same as name on an English card: "Charizard". What to search and sort by across languages (see the guide).
displayNamestring
A numberless card's name with its versions, where another card of the set's versions shares its name: "Pikachu (blue)" (see the guide).
defaultVariantstringalways present
The variant that stands for the card where one must (prices, a tile): by id in variants. Whose photo the card's picture is can be another variant's: read picture.front.of for that.
curl https://pokemon.cardcorpus.com/v1/sets/english/base-set.json
{
  "cards": [
    {
      "id": "4",
      "name": "Charizard",
      "number": { "printed": "4/102" },
      "rarity": "Holo Rare",
      "cardType": "pokemon",
      "language": "en",
      "credit": "Mitsuhiro Arita",
      "artists": [
        {
          "$kind": "artist",
          "id": "mitsuhiro-arita",
          "name": "Mitsuhiro Arita"
        }
      ],
      "released": { "date": "1999-01-09" },
      "species": [{ "$kind": "species", "id": 6, "name": "Charizard" }],
      "picture": { "front": { "image": "2aca2cf3e9ca6703b5edea32eb3177ea" } },
      "variants": [
        {
          "id": "unlimited-holo",
          "name": "Unlimited",
          "finish": "holo",
          // … 5 more fields
        },
        // … 6 more
      ],
      "links": {
        "reprints": [
          {
            "$kind": "card",
            "set": "english/base-set-2",
            "id": "4",
            "name": "Charizard",
            "englishName": "Charizard",
            "number": { "printed": "4/130", "short": "4" },
            "picture": { "front": { "image": "686fcda16c80652fbc98fd1d1c8c3b17" } },
            "differs": ["number"]
          },
          // … 7 more
        ],
        // … 2 more fields
      },
      // … 5 more fields
    },
    // … 101 more
  ],
  // … 18 more fields
}
200application/json: one card of the set's cards

GET /v1/cards/english.json is every card of a catalog in one list, so you can find a card by name or number without opening every set. There is one for each catalog: english, japanese and zh-hans. Fetch it once, keep it, and filter it in your own code.

Each row points at its card with set and id, and carries the card's name, number, language and image.

A card's name is as the card prints it, so a Japanese Charizard is リザードン. Every card also has englishName, so search and sort by that to find a card in any language.

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

// cards/{catalog}.json is every card of a catalog in one list: fetch it once and search it
const { cards } = await get("cards/english.json");
const found = cards.filter((c) => c.name === "Umbreon ex");

console.log(found.length, "cards named Umbreon ex");
for (const card of found.slice(0, 4)) {
  console.log(card.set, card.number.printed);
}
Prints
8 cards named Umbreon ex
english/ex-unseen-forces 112/115
english/2006-world-championships-deck-eeveelutions 112/115
english/sv-black-star-promos 176
english/prismatic-evolutions 060/131

Cards by Pokémon or artist

To list every card of one Pokémon, artist, character or promo, there is a ready-made file for each, oldest card first. See Pokémon, artists and promos.

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

// Every card of one Pokémon, oldest first. Charizard is No. 6. Its cards
// come a catalog at a time, and pokemon.json says which catalogs have any.
const { species } = await get("pokemon.json");
const { catalogs } = species.find((s) => s.dex === 6);
const parts = await Promise.all(catalogs.map((catalog) => get(`pokemon-cards/${catalog}/6.json`)));
const cards = parts
  .flatMap((part) => part.cards ?? [])
  .sort((a, b) => (a.released.sort < b.released.sort ? -1 : 1));
const { language } = await get("vocabulary.json");

const counts = {};
for (const card of cards) {
  const name = language[card.language].label;
  counts[name] = (counts[name] ?? 0) + 1;
}
console.log(cards.length, "cards, the first from", cards[0].released.date);
for (const [name, count] of Object.entries(counts)) {
  console.log(count, name);
}