Passare da pokemontcg.io a PkmnPrices

La Pokémon TCG API di pokemontcg.io è deprecata. La sua documentazione dice che le nuove registrazioni sono chiuse e che «existing API keys will continue to function through March 1, 2027». Se la tua app chiama api.pokemontcg.io, quella è la tua scadenza.

Questo articolo è la parte di codice del passaggio: come una richiesta a pokemontcg.io corrisponde alla nostra, qualche riga che ricostruisce l’oggetto tcgplayer.prices che il tuo codice probabilmente legge, e i campi delle carte senza equivalente. Gestiamo noi PkmnPrices, quindi valuta il consiglio di conseguenza. Se ti servono il testo completo delle carte e i dati di legalità, l’articolo di confronto tratta Scrydex, verso cui punta pokemontcg.io. Ogni dettaglio su pokemontcg.io è stato verificato nella sua documentazione il 26 ottobre 2026.

Cosa cambia

Autenticazione

Crea una chiave nella dashboard. Il piano gratuito non richiede una carta. I nomi degli header non distinguono le maiuscole, quindi il codice che invia già X-Api-Key continua a funzionare appena contiene una chiave PkmnPrices.

# pokemontcg.io
curl -H "X-Api-Key: $PTCG_KEY" \
  "https://api.pokemontcg.io/v2/cards?q=name:charizard&pageSize=3"

# PkmnPrices
curl -H "x-api-key: $PKMNPRICES_KEY" \
  "https://api.pkmnprices.com/v1/cards?name=charizard&per_page=3"

Ricerca

pokemontcg.io ha un linguaggio di query in q. Noi abbiamo parametri separati, quindi ogni clausola di un q diventa un parametro a sé.

Ritrovare la stessa carta

Un id di pokemontcg.io è un codice di set e un numero, base1-4. Il nostro è un intero senza relazione con quello. Cerca quindi il set per nome una volta e conserva il risultato.

const API = "https://api.pkmnprices.com/v1";

const get = async (path, params = {}) => {
  const url = new URL(API + path);
  for (const [key, value] of Object.entries(params)) {
    if (value !== undefined) url.searchParams.set(key, value);
  }
  const res = await fetch(url, { headers: { "x-api-key": process.env.PKMNPRICES_KEY } });
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
  return res.json();
};

// pokemontcg.io id "base1-4" becomes a set name plus a number here.
export const findCard = async (setName, number) => {
  const sets = await get("/sets", { name: setName });
  const set = sets.data.find((s) => s.name === setName);
  if (!set) throw new Error(`no set called ${setName}`);

  const cards = await get("/cards", { set_id: set.id, number });
  if (cards.data.length === 0) throw new Error(`no card ${number} in ${setName}`);

  // The list has no prices; the single-card call does.
  return get(`/cards/${cards.data[0].id}`);
};

La carta restituita contiene i suoi prezzi. La chiamata di lista nel mezzo no, per questo l’ultima riga è una seconda richiesta.

Prezzi

pokemontcg.io annida i prezzi sotto il marketplace e la stampa: card.tcgplayer.prices.holofoil.market. I nostri sono righe di un array prices, una per fonte, condizione e stampa:

{
  "source": "tcgplayer",
  "currency": "USD",
  "condition": "Near Mint",
  "variant": "Holofoil",
  "market_price": 412.5
}

Questo ricostruisce l’oggetto che il tuo codice legge già, per le tre stampe più usate dalle app:

// card.tcgplayer.prices.holofoil.market, rebuilt from the prices array.
const VARIANT_KEY = {
  Normal: "normal",
  Holofoil: "holofoil",
  "Reverse Holofoil": "reverseHolofoil",
};

export const tcgplayerPrices = (card) => {
  const prices = {};
  for (const row of card.prices) {
    if (row.source !== "tcgplayer" || row.condition !== "Near Mint") continue;
    const key = VARIANT_KEY[row.variant];
    if (key) prices[key] = { market: row.market_price };
  }
  return prices;
};

Alcuni campi non passano:

• low, mid, high e directLow non vengono restituiti. Ogni riga ha un solo market_price.
• Le medie e le tendenze di Cardmarket (trendPrice, avg1, avg7, avg30 e il resto) non vengono restituite. Il market_price di una riga Cardmarket è l’offerta attuale affidabile più bassa per quella condizione e stampa, in EUR, da Pro in su.
• Le prime edizioni compaiono come varianti a parte. Leggi le stringhe delle varianti in una risposta reale prima di associarle.

In cambio ottieni un prezzo per ogni condizione e non solo Near Mint, uno storico giornaliero dei prezzi fino a un anno, le inserzioni in diretta di TCGplayer e Cardmarket, e le vendite eBay. La documentazione descrive ciascuno.

Cosa non troverai

Le nostre carte hanno i campi che servono a un’app di prezzi e lasciano fuori il testo completo delle regole. Questi non hanno equivalente:

• legalities e regulationMark
• supertype e subtypes (esistono solo card_type e stage)
• rules, evolvesFrom, evolvesTo e nationalPokedexNumbers
• ancientTrait, e abilità e attacchi come oggetti strutturati: da noi sono testo
• Immagini piccola e grande: c’è un solo image_url
• Serie, data di uscita e ptcgoCode di un set: un set ha id, name, language e card_count

Se la tua app ne ha bisogno, tieni una copia locale per quelli e usa l’API per i prezzi. I dati JSON storici nel repository pokemon-tcg-data si possono ancora clonare, anche se il suo README lo definisce legacy e dice che il progetto sta per essere dismesso. Scrydex ha ereditato il database completo delle carte.

Crediti e paginazione

Un credito è un elemento restituito. Una pagina di 100 carte costa 100 crediti, e la lista non ha prezzi, quindi ogni consultazione di prezzo costa un credito in più. Pro consente 20.000 crediti al giorno.

Un’app che replica tutte le carte non sta in un giorno. Ci sono più di 80.000 carte, quindi elencarle tutte una volta costa più o meno altrettanti crediti: distribuiscilo su qualche giorno e conserva gli id. Per i prezzi di tutto il catalogo, l’esportazione del catalogo del piano Scale restituisce ogni prezzo attuale in un solo file, e un download non costa crediti.

Passare senza un giorno X

Lascia attivo pokemontcg.io fino a marzo. Prendi una chiave gratuita ed esegui qualche consultazione con il codice qui sopra accanto alle tue chiamate attuali, così puoi confrontare i numeri. Salva il nostro id della carta accanto al tuo. Poi sposta le letture e lascia la vecchia chiave finché non sei sicuro. La pagina dei piani elenca cosa include ogni livello.

Quando smettono di funzionare le chiavi di pokemontcg.io?

La sua documentazione dice che le chiavi esistenti continuano a funzionare fino al 1° marzo 2027. Le nuove registrazioni sono già chiuse.

Posso usare la mia chiave pokemontcg.io con PkmnPrices?

No. Crea una chiave PkmnPrices nella dashboard. Il piano gratuito dà 500 crediti al giorno e non richiede una carta.

PkmnPrices restituisce dati di legalità o di rotazione?

No. Le carte hanno prezzi, attributi come stadio, tipo, PS, debolezza e testo degli attacchi, e un’immagine, ma non legalità né marchi di regolamentazione. Tieni una copia locale per quelli.

Esiste un SDK?

Sì, SDK ufficiali per JavaScript e Python. La pagina SDK della documentazione mostra entrambi.