Conventions and types
A handful of rules hold in every file. Knowing them saves guessing.
Ids
- Store ids, not names or urls. An id never changes once published. Names get corrected and urls are built from recipes.
- Treat ids as opaque. A card id is often its number (
4) but not always (4-charizard), so don't build one or take one apart. - A card's address is two ids (set and card), and a variant's is three (set, card and variant).
- If an address ever stops resolving,
moved.jsonlists where it went.
Absent means unknown
There are no nulls. A field that isn't known or doesn't apply is left out, and a list with nothing in it is left out too, so read both with a default. Counts (cardCount and the like) are always present.
Pointers
A reference from one thing to another is a pointer: an object with $kind and the ids that find its target, such as { "$kind": "card", "set": "english/base-set", "id": "4" }. Whatever has a $kind says its own id as id, the same id the target has in its own file. The other ids beside it say what it is in: a card's set, a variant's set and card.
Many pointers also carry a copy of the target's name, so a list can be drawn without following them. To follow one, index.json has a recipe per kind under pointers. More in Links between cards.
const get = (path) =>
fetch(`https://pokemon.cardcorpus.com/v1/${path}`).then((res) => res.json());
// A pointer: what kind of thing it names, its own id, and the ids of
// what it is in (a variant is in a card, which is in a set)
const pointer = {
$kind: "variant",
set: "english/base-set",
card: "4",
id: "unlimited-holo",
};
// index.json has one recipe per kind. For "variant" it is:
// file: "sets/{set}.json"
// path: [{ list: "cards", match: "id", by: "card" },
// { list: "variants", match: "id", by: "id" }]
const { pointers } = await get("index.json");
async function follow(pointer) {
const recipe = pointers[pointer.$kind];
// 1. Put the pointer's ids into the file name, and fetch it
const file = recipe.file.replace(/\{(\w+)\}/g, (_, id) => pointer[id]);
let found = await get(file);
// 2. Each step of the path picks one item out of a list
for (const step of recipe.path) {
found = found[step.list].find(
(item) => item[step.match] === pointer[step.by],
);
}
return found;
}
// sets/english/base-set.json → cards "4" → variants "unlimited-holo"
const variant = await follow(pointer);
console.log("variant:", variant.name);
// A card pointer stops one step earlier
const card = await follow({ $kind: "card", set: pointer.set, id: "4" });
console.log("card:", card.name, card.number.printed);
// A set pointer has an empty path: it is the whole file
const set = await follow({ $kind: "set", id: pointer.set });
console.log("set:", set.name);Coded words
Fields such as rarity, finish, edition, stamp, language and cardType hold a word from a fixed list. GET /v1/vocabulary.json has every list, and for every word the label to show and, for many, a tell: how to spot it on a card.
The lists only grow. A word is never renamed in place, so it is safe to switch on one, as long as an unknown word falls through to its label.
curl https://pokemon.cardcorpus.com/v1/vocabulary.json{
"finish": {
"holo": {
"label": "Holo",
"tell": "The picture shines; the rest of the card doesn't.",
"sources": [
{
"title": "Bulbapedia: Holofoil",
"url": "https://bulbapedia.bulbagarden.net/wiki/Holofoil"
}
],
"useCount": 34903
},
"reverse_holo": {
"label": "Reverse holo",
"tell": "Everything but the picture shines.",
// … 2 more fields
},
// … 34 more fields
},
"rarity": {
"Holo Rare": { "label": "Holo Rare", "tier": "holo", "useCount": 2653 },
// … 51 more fields
},
// … 14 more fields
}Schemas and types
Every file has a JSON Schema (draft 2020-12) with a description on every field. index.json names each file's schema under files, and every response names its own in a Link header with rel="describedby".
Generate your types from the schemas and they stay right as fields are added. The API reference shows each schema as a field list beside a live example.
The schemas also mark what JSON Schema can't say, under x-cc: which fields are pointers and to what (ref), which hold a coded word and from which list (vocabulary), and which hold an image id (picture).
curl https://pokemon.cardcorpus.com/v1/index.json{
"name": "CardCorpus",
"version": "2.0.0",
"pictures": {
"sized": "https://img.cardcorpus.com/s1/{width}/{id}.avif",
"widths": [240, 480, 960]
},
"prices": {
"latest": "https://prices.cardcorpus.com/{set}.json",
"sets": "https://prices.cardcorpus.com/sets.json?sets={sets}",
"history": "https://prices.cardcorpus.com/history/{set}/{card}.json",
"rates": "https://prices.cardcorpus.com/rates.json",
"schemas": {
"latest": "schema/prices.schema.json",
"sets": "schema/prices-sets.schema.json",
"history": "schema/price-history.schema.json",
"rates": "schema/exchange-rates.schema.json"
}
},
"counts": {
"setCount": 1042,
"cardCount": 90227,
"variantCount": 143343,
// … 13 more fields
},
"files": [
{ "file": "index.json", "schema": "schema/index.schema.json" },
{
"file": "sets/{catalog}.json",
"schema": "schema/sets.schema.json"
},
{ "file": "sets/{set}.json", "schema": "schema/set.schema.json" },
// … 20 more
],
"pointers": {
"card": {
"file": "sets/{set}.json",
"path": [{ "list": "cards", "match": "id", "by": "id" }]
},
// … 14 more fields
},
// … 4 more fields
}Start from index.json
GET /v1/index.json is the map of everything: every file and its schema, the pointer recipes, the image, price and marketplace url recipes, and how many of each thing there are. Code that reads its recipes from there keeps working when a host changes.
Caching and updates
Files are served with Cache-Control: public, max-age=300 and change in place when the data is updated. There are no versions in the urls under /v1; for a fixed snapshot, use a release from the repository.
Every file has an ETag. To check for updates, send it back as If-None-Match: an unchanged file answers 304 Not Modified with no body. Check each file you keep this way rather than fetching it whole again: index.json doesn't change with every correction to a card.
Please send a User-Agent naming your app and a way to reach you (a URL or an email), so we can warn you before a breaking change. A wrong address answers a JSON 404 that says where to start.